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1  O  verv  ie  w 


The  artillery  editor  allows  the  user  to  drop  arbitrary  artillery  rounds  on  the  DIS  battlefield. 
The  editor  supports  two  modes  of  operation: 

Set  up  then  Fire 

In  this  mode,  the  user  selects  the  Mode  Sat  Up  Hisaion,  then  sets  the  location,  round 
types,  quantities,  etc.  When  everything  is  set,  the  user  selects  the  Mode  Firm  Niasion 
which  sends  the  selected  detonations.  The  Mode  then  automatically  returns  to  Sat  Up 
Niaaion. 

Poiat  to  shoot 

In  this  mode,  the  user  selects  the  Mode  Fira  Hhan  Location  la  Sat,  then  sets  every* 
thing  except  the  location.  When  the  round  types,  quantities,  etc.  are  as  desired,  the 
user  selects  Location  then  clicks  on  the  map.  The  mission  will  be  fired  when  the  user 
releases  the  mouse  button.  A  separate  mission  will  fire  for  each  click. 

The  artillery  editor  is  not  reinitialized  when  it  is  raised,  so  that  the  default  values  for  each 
mission  wiU  be  whatever  values  were  used  in  the  previous  mission. 
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Chapter  2:  Functions 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libartyedit,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  artyedit  Jnit 


void  artyedit.initO 


artyedit.init  initializes  libartyedit.  Call  the  before  any  other  libartyedit  function. 


2.2  artyedit_init-gui 


int32  artyadit.lnit.gui(data.path,  reader.f lags ,  gui, 

tactaap.  tcc,  aap.erase.gc ,  sensitive, 
refresh.event,  db,  ctdb,  valve,  sim.addr, 
event.id,  exercise,  protocol) 

*data.path; 
reader.f lags; 
gui; 

tactaap; 
tcc; 

a^.erase.gc; 
sensitive; 


char 
uint32 
SGUI.PTR 
TAC1TIAP.PTR 
C00RD_TCC.Fni 
GC 

SHSTVE.WIHDOW_PTR 


CALLBACK.EVENT_PTR  ref resh.event ; 


PO.DATABASE 

CTDB 

PV.VALVE.PTR 

SiaulationAddress 

int32 

int32 

int32 


*db; 

*ctdb; 
valve; 
*siB.addr; 
•event.id; 
exercise; 
protocol ; 


‘data.path’ 

Specifies  source  directory  f<}r  data  files 

‘reader .flags’ 

Specifies  data  file  resiling  flags 

‘gui’  Specifies  the  GUI 
‘tactaap’  Specifies  the  tactical  map 
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’tcc’  Specifies  the  coordinate  system 

‘aap.erase.gc’ 

Specifies  the  GC  used  to  erase  on  the  map 

‘sensitive’ 

Specifies  the  sensitive  window 
‘refresh,  event’ 

Specifies  the  event  invoked  when  the  map  is  refreshed 
‘db’  Specifies  the  PO  database 

‘ctdb’  Specifies  the  terrain  database 

‘valve’  Specifies  the  packet  valve  for  transmission  of  detonations 

‘siB_addr’ 

Specifies  the  simulation  address  / 

‘event.id’ 

Specifies,  by  referenence,  the  gloabl  application  event  ID  which  is  used,  then  incre¬ 
mented  for  each  outgoing  detonation 

‘exercise’ 

Specifies  the  exercise  on  which  PDUs  should  be  sent 

‘protocol’ 

Specifies  the  protocol  to  use  (SIMNET,  DIS  1.0,  DIS  2.0,  etc.) 

art7edit.init.gui  create  the  artillery  tool.  The  data.path  and  reader.flags  are  used  to 
read  the  editor  definition  file,  and  are  as  in  reader.read.  A  non-zero  return  value  indicates  a 
libreader  error  occured. 
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Cliaplor  I:  Overview 


1  Overview 

l.il).\>>i,nii  iiii|>l(“iiM'iii'<  I  li«'  iiii>>i<Hi  ii^'iv.iiiiM'iii  ••(liini  .  (  iirnMitly  i  his  (>(iii(>i  (  .m  <m|y  he  used  i.. 
iissi]i>ii  >1  .siii^,l('  unit  a  iiiissinti.  liowostM .  in  iIk-  Iiiiiii<*  it  \^ill  iii;Mia>;<>  cxnc  iil ion  iiialtid's.  im 

soiiii'  ()l  li«'r  complex  assi«iim<'iit  pai  adium. 


(  liapU'i  2:  I 


2  Usage 


I’ll*'  >ori\vai'<'  lilirarv  'libassign. a'  >.li(iiil<l  Ix'  Imih  and  insiall*'*!  in  lli*'  diincloiv 
•/common/lib/',  ^■^^n  will  aUo  nc*-*!  lln'  iK-adcr  lilc  'libassign .h'  wliidi  slnnild  lx-  in^lall<'d  in  llic 
(lirf'cior.v  '/conunon/include/libinc/'.  II  iIk'n*'  lilos  an-  noi  iiisiall*'*!.  yon  nood  lo  do  a  'make'  in 
ill*'  lil)a^.>«i»n  miiiicc  dii<'(lorv.  If  I  licx'  (il<‘>  arc  ali<'a<ly  bnill.  yon  *an  ^ki|)  I  hr  M'dion  on  l)nildinn 
lil)a.ssij>ii. 


2.1  Building  Libassign 

I  II*'  liliassif»n  sour**'  lih'sar*'  roniul  in  t  In*  dii<'*  tory  '/common/libsrc/libassign'.  'RCS'  (onnai 
vorsion^  of  lli«'  fih's  *  an  hr  found  in  '/nf s/conunon.src/libsrc/libassign*. 

If  I  hr  dirrriory  'common/libsrc/libassign'  dues  not  exist  on  your  inadiine.  yon  should  use 
the  'genbuild'  rominand  to  nixiatc  the  coiniiion  direetory  hioiarrhy. 

To  hnihl  and  install  the  lihrary.  do  the  hillowinj*: 

#  cd  common/libsrc/libassign 

#  CO  RCS/*,v 

#  make  install 

This  shonid  coinpile  the  lihrary  'libassign. a*  and  install  it  and  the  header  file  'libassign. h' 
in  the  standard  directories.  If  any  errors  ocrur  during,  compilation,  yon  may  need  to  adjust  the 
source  <o*l«'  or  'Makefile*  for  the  platform  on  which  yon  are  compiling,  lihassign  shonid  compile 
without  <'rrors  *>n  th<’  following  platforms; 


•  .Mip.s 

•  S(il  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libassign 


l.ihassign  ran  he  link*'*!  into  an  application  program  with  the  following  litik  time  flags:  'Id 
[source  .o  files]  -L/common/lib  -lassign  [other  libraries]'.  If  yonr  compiler  does  not  sup- 


I 


l.il).\^^iRll  I’loniiimiiK'i  N  (iiii<l< 


|H)it  ’-L'  .\viitax.  yoti  can  iim'  tin'  an  liivo  <’X|>licilly:  Id  [source  .o  files] 
/common/lib/libassign .  a'. 

I.iha^sit'ii  <l‘’|»iMi{|»  (lin'd  ly  on  1 1n*  roll(»\\  in«  lilnarics:  lil(sar*'ni.  Iil)ta(  l  ina|).  lilxoordinalrs.  Iil> 
sensitive',  liltcallhack.  lil>|>o.  lilx'dilor.  and  lilii('ad(>r. 


(■|ia|)l(‘r  .{:  rmu  liuii 


3  Functions 


1  li(‘  Ibllowiiij*  M(‘(  l ion-'  dt'sc  riltc  c.k  h  IntHiioii  l»\  lil>ii>i>inii.  iii(  liuliiii*  I  h<‘  ruriiial  an 

iiH'aiiiii)^  ol  il>  insiiiitM'iil and  lln‘  nn'.iniin;  nl  it'  n'liirn  valin*'  |il  any). 


3.1  assign  Jnit 

void  assign. initO 


assign.init  iiiitiali/i‘>  lil)a>'iiin. 


< '.ill  till*  any  oiln'r  lil>a"ii*n  rnncli«)n. 


3.2  assign Jnit-gui 


EDT.EDITOR.PTR  assign.init 


char 

uint32 

Widget 

SGUI.PTR 

TACTMAP.PTR 

COORD.TCC.PTR 

GC 

SNSTVE.WINDOW.PTR 

CALLBACK_EVENT.PTR 

PO.DATABASE 

ASSIGN.EXIT.FUNCTION 

ADDRESS 


.guiCdata.path,  reader.f lags ,  dialog.parent , 
gui,  tactmap,  tcc,  map_erase.gc , 
sensitive,  refresh.event,  db, 
exit. fen,  exit.arg,  reinit.fcn) 

•data. path; 
reader. flags; 
dialog.parent; 

gui: 

tactmap; 

tcc; 

map.erase.gc; 

sensitive; 

refresh.event; 

•db; 

exit. fen; 
exit.arg; 


ASSIGN.REINIT.FUNCTI OH  re x n x t .f cn ; 


■data.path* 

llio  dii<'r»iti\  * . .  lili*'  am 

‘reader. flags' 

S|)cnrK's  na}*>  i<>  I"  ■  -■  ->  reader.read  wIkmi  r(’a<riii)i;  data  lilt's 

'dialog.parent' 

Sporifios  fop-lfv**!  -  '  •  •  •  .  -•  •mid  part'iit  |><t|>ii|>  dialogs 

’gui'  SiK'fifu's  lilt’ S.\l  «.l  I 


G 


'tactmap'  Spocifios  the  lactiral  ina|i 

'tcc'  S|>«*{i(i<>s  iIk'  iiiaj)  cooi dinaU' 

'map.erase.gc' 

.S|)r(i(i«'N  llic  (iC  wlii(li  (an  crax'  lliiii!>>  from  llic  lacliial  itiaj) 

'sensitive' 

S|)(><i(ios  iIk'  s('ii>iliv('  window  lor  tin'  iarii(al  nia|) 

'refresh.event' 

Spncifios  tin'  ('vont  wliicli  lil('^  wln'u  lli('  luap  is  rrfn'sliod 

'db'  Spocilics  llin  pcnsislcnl  ol)i<‘(l  database' 

'exit.fcn,  exit.arg' 

Spc'cily  a  liiiiction  to  call  wli('n  tin'  assip,iiiii<'nt  is  coinp|(<t('d 
Teinit.fcn' 

Spocily  a  rnncti<jn  tocall  to  r('iniliaii/<‘ a  task  Iraiiu' prior  to assi^niiK'iit  (pass  taskedit. 

assign.init.gui  rroato  tlio  mission  assi»iim('iit  odilor.  I'lio  data  lib'  ('delobj  .rdr')  is  read 
citlior  Irom  or  I  ho  spocifiod  data  path.  <h‘p('ndiii.t!;  upon  lli<*  reader.f  lags.  I'lio  reader.flags 
aro  as  in  reader.read.  .\  NULL  roinrn  \alm*  indicatos  an  orror  orciirod. 

riio  exit_fcn  should  Ito  doclarod  as  lollows: 

void  exit.fcnCexit.arg,  status) 

ADDRESS  exit.arg; 

EDT.EXIT.STATUS  status; 


3.3  assigiijset.unit 


void  assign.set.unit (editor,  unit.id) 
EDT.EDITOR.PTR  editor; 

ObjectID  eunit.id; 


'editor'  .Spocilics  tlio  assignniont  editor 
'unit.id*  .Spocifios  tlio  iinil  for  dofanlt  assiKiiiiioiil 


assign.set.unit  initiali/«‘s  the  unit  hold  <rf  iho  rtiiiiiiiig  a.s.signiiiont  oditor  to  llio  passed  valno. 


remit  • 


3.4  assign.^et_taskfranie 


CliaiHor  :i: 


void  assign.Bot.taskframeCeditor ,  taskframe.id) 

EDT.EDITOR.PTR  editor; 

ObjectID  otaskframe.id; 

‘editor'  Siwcilio  i lie  il^MKlllll‘'ll1  ('«lii(»r 

'taskframe.id' 

S|M>(  ili**>  tlt<'  laNklVmiK'  loi  ili'laiill 

assign.set.taskframe  initiilliz«‘^  (Ik-  taskframe  Tk-UI  of  ilio  . . .  assiRiiinoiit  «-«litor  to  tli<- 

|>asso<t  value. 


3.5  assign_niake_assignnieiit 


void  as8ign_make.assignnient(gui ,  unit,  frame,  assigner,  instruction) 
SGUI.PTR  gui; 

ObjectID  *unit; 

ObjectID  *frame; 

ObjectID  *aa8igner; 

Taskinatallationinstruction  instruction; 


•gui*  S|)ocin<'s  (lie  (iri 

•unit*  .S|ie<in«>s  (lie  unit  to  exectite  the  mission 

•frame*  Sporifies  a  fraino  of  the  mission  to  oxonite  (aiitomatirally  finds  first  frame) 


‘assigner 


Speeifies  the  unit  responsible  for  making,  the  assignment  (pa.ss  NULL  to  indicate  tin 
nsec) 


•instruction 


■Specifies  how  to  start  the  mission 

assign.make_assignment  does  an  assignment,  as  tfiongh  (he  user  had  selected  a  unit  and  fraiin 
from  the  assignment  editor. 
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1  Overview 


Libbalgun  implements  an  instance  of  the  gun  class  of  components.  It  provides  a  low-fidelity 
model  of  generic  ballistic  gun  behavior  which  is  suitable  for  ModSAF  tank  main  guns  and  machine 
guns,  libbalgun  guns  support  burst  shooting,  multiple  types  of  munitions,  and  table  driven  hit 
probabilities.  Also,  the  capability  to  hit  un-intended  targets  is  supported. 

The  parameters  of  a  generic  ballistic  gun  are  specified  in  the  configuration  file  for  the  vehicle 
containing  such  a  gun  as  follows: 


(SM_BallieticGun  (physdb.name  <naffle  of  gun>) 

(•ensor.nane  <naBe  of  tracking  sensor>) 
(hit_obscuring_v«hicles  <true  I  fal8e>) 

(rates  <min-elevation-‘rate>  <maz-elevation*rate>) 
(aagazlne.slze  <n>) 

(loading.block  <n>) 

(load.tiffle  <integer  Bdlli8econds>) 

(track_tlme  <integer  fflllliseconds>) 

(munition  <munition-table> 

<munition’*table> 

...» 


The  <name  of  gun>  must  match  the  name  of  a  gun  as  specified  in  the  libphysdb  database. 
The  <name  of  tracking  sen8or>  must  match  the  name  of  some  sensor  component  of  the  vehicle, 
hit.obscuring. vehicles  indicates  whether  this  gun  can  accidentally  hit  vehicles  that  obscure  an 
intended  target.  The  rates  for  elevation  are  in  degrees  per  second,  magazine.size  indicates  how 
many  rounds  of  a  munition  may  be  simultaneously  loaded  in  the  gun.  The  time  to  load  up  to 
loading.block  rounds  is  specified  by  load_time. 

A  sninition-table  is  of  the  form: 


(<munition  object  type>  (round. velocity  <real  meters/seO) 

(rate  <integer>  burst  rate  8hell8/8ec>) 
(mass  <real  kg>} 

(min_range  <real  meters>} 

(iaaz_range  <real  meters>) 

(hit.table  <hit>table*’filename>) 
(tracktime.table  <tracktime-table>) ) 


<munition  object  type>  indicates  the  ‘librdrconst’  object  type  that  will  be  sent  in  the  Fire 
and  Impact  PDUs.  rate  indicates  the  maximum  sustainable  burst  rate  in  rounds  per  minute.  A 
value  of  -1  means  the  gun  can  be  fired  as  fast  as  it  has  rounds  available.  A  rate  of  -1  should  not 
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be  used  if  the  gun  has  a  magazine  size  larger  than  1  (this  would  imply  that  the  entire  magazine 
could  be  shot  at  once,  min^range  and  nax.range  should  be  considered  as  minimum  and  maximum 
effective  ranges. 

A  tracktiae.table  is  of  the  form: 


(<r«al  moving  f irar_faetor>  <r«al  moving_targ«t_factor> 

(<Taal  range  metera>  <fiTst_Bed  inaec8>  <sub_med  Dsec8>  <8ub_fized  iD8ec8>) 
(<real  range  aeter8>  <fir8t_med  B8ec8>  <8ub_Bed  iii8ec8>  <sub_fized  ]iisecs>) 


The  tracktime  table  defines  how  long  the  target  will  be  tracked  before  firing.  The  moving 
factors  are  used  to  modify  the  tracktime  for  these  conditions.  The  first_med  describes  the  lognormal 
distribution  for  the  first  shot  by  a  firer  at  a  specific  target.  The  subuned  and  subjixed  are  for 
subsequent  shots  at  a  target.  The  median  and  fixed  values  are  not  interpolated  for  range.  The 
values  are  also  not  range-limited.  Finally,  if  either  moving  factor  is  -1,  then  the  tracktime  will  be 
0.  The  actual  calculation  of  the  tracktime  is  described  below. 

So  a  simple  table  could  be:  (1.0  1.0  (0.0  3000  0  0)) 

This  table  says  that  a)  moving  firer  and  target  have  no  effect  on  tracktime;  b)  the  first  shot’s 
tracktime  will  have  a  median  of  3000  msecs,  regardless  of  range;  c)  the  subsequent  shots’  tracktimes 
will  be  0. 


The  hit-table-f  ilename  has  a  table,  derived  directly  from  AMSAA  approved  weapon  delivery 
accuracy  data,  with  the  following  form: 

( 

(<ranga>  <tiBe  of  flight> 

<horizontal  fixed  bia8>  <vartical  fixed  bia8> 

<horizontal  variable  bias>  <vertical  variable  bias> 

Khorizontad  random  error>  <vortlcal  random  error> 

<horizontal  stationary/moving  add-on  di8persion> 

<vertical  stationary/moving  add-on  di8per8ion> 

<horizontal  stationary/moving  subtractive  dispersion^ 

<vertical  stationary/moving  subtractive  di8per8ion> 

<horizontal  sioving/stationary  add-on  dispersion> 

<vortical  moving/stationary  add-on  disporsion> 

<horizontal  moving/stationary  subtractive  di8per8ion> 

<vertical  moving/stationary  subtractive  di8per8ion>) 

(<range>  <time  of  flight>  ...) 

...) 
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) 

range  is  the  distance  between  the  shooter  and  the  target,  (real  in  meters) 

tine  of  flight  is  the  time  of  flight  for  the  specific  range,  (real  in  seconds) 

horizontal  fixed  bias  and  vertical  fixed  bias  are  fixed  discrepancies  between  the  desired 
aim-point  and  the  actual  hit  point,  (real  in  mils) 

horizontal  variable  bias  and  vertical  variable  bias  are  occasional  discrepancies  between 
the  desired  aim-point  and  the  actual  liit  point,  (std  deviation,  real  in  mils) 

horizontal  random  error  and  vertical  random  error  are  the  random  error  factors,  (std  de¬ 
viation,  real  in  mils) 

horizontal  stationary/moving  add-on  dispersion  and  vertical  stationary/moving  add¬ 
on  dispersion  are  add-on  dispersion  when  tiic  shooter  is  stationary  and  the  target  is  moving,  (std 
deviation,  real  in  mils) 

horizontal  stationary /moving  subtractive  dispersion  and  vertical  stationary /moving 
subtractive  dispersion  are  subtractive  dispersion  when  the  shooter  is  stationary  and  the  target 
is  moving,  (std  deviation,  real  in  mils) 

horizontal  moving/ stationary  add-on  dispersion  and  vertical  moving/stationary  add¬ 
on  dispersion  are  add-on  dispersion  when  the  shooter  is  moving  and  the  target  is  stationary,  (std 
deviation,  real  in  mils) 

horizontal  anving/stationary  subtractive  dispersion  and  vertical  moving/stationary 
subtractive  dispersion  are  subtractive  dispersion  when  the  shooter  is  moving  and  the  target  is 
stationary,  (std  deviation,  real  in  mils) 

The  algorithm  to  calculate  mis.sed  di'«taiicc  is  described  below: 

1.  Look  up  the  hit  table  entry  fnr  a  civf'ii  range. 

2.  Calculate  the  overall  bias  (Mi. 

a.  Extract  the  fixed  bias  il  •.  :!,<•  variable  bias  standard  deviation  (V^TDJ)£V)  from 

the  entry. 

b.  The  variable  bias  (V)  ••  I>v  drawing  a  normal  random  number  from  the  variable 
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bias  distribution  with  zero  mean,  and  standard  deviation  deviation  is  V_STD_DEV.  V  := 
rndjiormal^istribution(0.0,  VJSTDJDEV) 

c.  The  overall  bias  is  calculated  by  adding  F  and  V.  B  =  F  V 

3.  Calculate  the  overall  error  (E). 

a.  Extract  the  random  error  standard  deviation  (R^TD  J)EV),  the  add-on  dispersion  standard 
deviation  (A_STD_DEV)  and  the  subtractive  dispersion  standard  deviation  (SJSTD_DEV). 

b.  Calculate  overall  random  error  standard  deviation  (E_STDJ)EV)  by  adding  the  variances 
of  the  random  error  and  add-on  dispersion.  Then  subtract  the  variance  of  the  subtractive 
dispersion  and  take  the  square  root  of  the  result.  EJSTD_DEV  =  sqrt(R3TD-DEV"2  ♦ 
A^TDJ)EV-2  -  S^TDJ)EV-2) 

c.  The  overall  error  is  calculated  by  drawing  a  normal  random  number  from  the  overall 
random  error  distribution  with  zero  mean,  and  standard  deviation  is  EJ5TD_DEV.  E  = 
rndjiormaljdistribution(0.0,  E^TD_DEV) 

4.  Calculate  the  missed  distance. 

a.  Given  the  overall  bias  (B)  and  overall  error  (£),  the  miss  distance  in  mils  (M_MILS)  can  be 
calculated  as  M_MILS  =  B  4^  E 

b.  Given  the  range  (R),  the  missed  distance  in  meters  (MJblETERS)  can  be  calculated  as 
M3IETERS  =  R*tan(MIL-TOJlAD(M3IILS)) 

»»»>  ../acu/libbalgun.te;dnfo  Libbalgun  supports  up  to  4  instantiations  per  vehicle  (i.e.,  a 
vehicle  can  have  up  to  4  generic  ballistic  guns).  This  number  can  be  easily  changed  by  recompUation. 

The  libbalgun  library  defines  a  common  set  of  functions  (and  the  semantics  of  those  functions) 
which  are  invoked  on  instances  of  the  guns  class  (such  as  those  instantiated  by  libbalgun  or  libm- 
launcher).  It  is  possible  to  modify  the  ballistic  gun  model  by  changing  an  exisiting  guns  interface 
function  or  by  adding  a  completely  new  function. 

To  modify  an  existing  libbalgun  interface  function  would  require  the  following  actions: 

1.  If  the  change  occurs  only  in  the  function  body,  a  change  to  the  function  code  in  the  libbalgun 
library  if  all  that  is  needed.  If  the  change  occurs  to  the  function’s  argument  list,  change 
the  function  code  in  the  libbalgun  library  and  the  guns  interface  structure  definition  found 
in  libguns.h.  Also  to  maintain  the  common  guns  interface,  change  the  code  for  the  modified 
function  in  any  other  gun  specific  component  library  (such  as  libmlauncher). 

2.  Recompile  ModSAF. 


To  add  an  additional  libbalgun  function  to  the  current  model  would  require  the  following  actions: 
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1.  Write  the  function  as  part  of  the  Ubbalgun  library.  The  function  is  written  in  the  code  that 
manages  the  Ubbalgun  class  information  attached  to  each  vehicle  (bgun_class.c). 

2.  Add  the  function  and  its  declaration  to  any  of  the  other  gun  specific  component  Ubraries.  This 
maintains  the  common  guns  interface. 

3.  In  the  Ubguns  source  code  that  handles  libguns  initialization  processing,  include  a  func- 
tion_nuiaber,  function  entry  identifying  the  new  function  for  the  cnpnt.define. instance 
function  and  every  other  gun  instance  library  (such  as  Ubmlauncher). 

4.  In  libguns.h,  add  an  entry  to  identify  the  new  macro  aud  associate  it  with  a  function  code 
number.  This  new  addition  means  that  the  number  of  guns  interface  functions  must  be  incre¬ 
mented  by  one.  The  guns  interface  structure  definition  that  appears  in  libguns.h  must  include 
a  structure  to  define  the  new  function’s  argument  list. 

5.  Recompile  ModSAF. 

To  replace  this  ballistic  gun  model  with  a  completely  different  one  would  require  the  following 
actions: 

1.  Decide  on  the  get  functions  and  set  functions  that  would  be  required  in  the  new  model.  Try  to 
map  these  needed  functions  to  the  existing  guns  interface.  A  function  can  map  if  its  argument 
list  can  remaun  the  same.  Functions  that  can  not  map  must  be  added  to  the  guns  interface. 

2.  For  those  functions  that  can  map  to  the  existing  guns  interface  but  whose  code  body  you  want 
to  change,  edit  the  code  for  the  function  in  the  Ubbalgun  source  file  that  contains  the  code  to 
manage  the  Ubbalgun  class  information  (bgunjclass.c). 

3.  For  those  functions  that  can’t  map  to  the  existing  guns  interface,  luld  an  additional  function 
to  the  guns  interface.  The  addition  procedure  was  described  above. 

4.  Recompile  ModSAF. 

If  an  interface  function  is  no  longer  needed,  it  is  possible  but  not  required,  to  remove  it.  Deletion 
of  an  interface  function  is  only  aUowed  when  that  function  is  not  needed  in  any  of  the  specific 
component  Ubraries, 

The  deletion  process  requires  these  steps: 

1.  Delete  the  function  code  from  each  specific  component  Ubrary. 

2.  In  the  generic  component  library,  remove  the  " function jiumber,  function"  entry  identifying 
the  excess  function  in  the  "cmpntjdefineJnstance”  function  caU.  This  function  caU  is  found  in 
the  Ubrary’s  initialization  code  segment.  In  the  library’s  pubUc  header  file,  remove  the  entry 
for  the  excess  macro  and  its  associatiated  function  code  number.  Decrease  the  number  of 
inter&ce  functions  by  one.  Delete  the  structure  that  defines  the  excess  function’s  argument 
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list  in  the  interface  structure  definition. 
3.  Recompile  ModSAF. 
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2  Algorithms 


The  following  sections  describe  the  tick  and  firing  event  processing  algorithms  used  by  libbalgun. 


2.1  Gun  Tick  Processing 

When  a  gun  is  ticked  via  bgun_tick(vehicle.id,  ctdb)  the  following  processing  occurs: 

1.  Retrieve  the  name  of  the  sensor  used  by  this  gun. 

2.  Calculate  dT,  the  time  period  between  the  last  tick  and  this  tick. 

3.  If  the  gun’s  state  is  BALGUH_STATE.DESTI10YED  then  exit,  otherwise  do  the  ballistic  gun  simu¬ 
lation  by  invoking  three  independent  state  machines:  Loader,  Tracker,  and  Firer.  Loader,  im¬ 
plemented  via  the  bgun_loader_tick  function,  does  loading  or  unloading  operations  on  quan¬ 
tities  of  requested  munition.  Tracker,  implemented  via  the  bgun_tracker_tick  function,  does 
tracking  operations  on  requested  targets  or  locations.  Firer,  invoked  via  the  bgun_f  irer.tick 
function,  does  shooting  operations  on  requested  targets  or  locations.  These  functions  which 
are  each  passed  the  argument  list,  (vehicle.id,  user_data.handle,  gun,  dT) ,  are  described 
below. 


2.2  bgun_loader_tick 

The  processing  for  bgun.loador_tick  (which  is  determined  by  the  gun’s  loading  state)  is  as 
follows: 

•  If  the  loading  state  is  BALGUII_LOADING_STATE_IOLE,  then  exit  if  the  requested  transfer  quantity 
is  0.  Otherwise  call  libsupplies  via  the  function  supp.get.anount  to  see  how  many  rounds  are 
currently  in  storage.  A  requested  transfer  quantity  greater  than  0  implies  an  intended  load 
and  a  requested  transfer  quantity  less  than  0  implies  an  intended  unload.  For  an  intended 
load,  clip  the  request  if  necessary,  down  to  the  amount  available  in  storage  or  the  amount  that 
there  is  enough  room  for  in  the  breach.  If  the  requested  transfer  quantity  gets  clipped  down 
to  zero  then  exit,  otherwise  change  the  loading  state  to  BALGUN_L0ADIHG.STATE_L0ADIII6.  For 
an  intended  unload,  if  there  aren’t  enough  rounds  in  the  breach  for  the  requested  transfer 
quantity  to  get  unloaded,  change  the  request  to  reflect  the  amount  currently  loaded.  If  the 
change  sets  the  requested  transfer  quantity  to  zero  then  exit,  otherwise  set  the  loading  state 
to  BALGUH.L0ADI1IG_STATE_UNL0ADIRG.  Set  the  loader  time  to  the  load  time  specified  in  the 
configuration  file. 
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•  If  the  loading  state  is  BALCUN.LOADING.STATE.LOADING,  then  reduce  the  loading  time  by  the 
input  dT,  the  time  between  ticks.  If  the  loader  time  is  still  greater  than  zero,  not  enough 
time  has  elapsed  between  ticks  to  load  a  round,  so  exit.  Otherwise  simulate  the  loading  of  one 
round  by  increasing  the  loaded  quantity  by  one  and  reducing  the  requested  transfer  quantity 
by  one.  Invoke  libsupplies  to  decrcnieiu  the  munition  amount  in  the  storage  area  by  one 
round.  If  the  requested  transfer  quantity  has  dropped  down  to  zero,  set  the  loading  state  to 
BALGUN.LOADING.STATE.IDLE,  otherwise  reset  the  loader  time  back  to  the  load  time  of  the 
configuration  file. 

•  If  the  loading  state  is  BALGUN.LOAOING.STATE.UNLOADING,  then  reduce  the  loader  time  by  the 
input  dT,  the  time  between  ticks.  If  the  loader  time  is  still  greater  than  zero,  not  enough 
time  has  elapsed  between  ticks  to  unload  a  round,  so  exit.  Otherwise  simulate  the  unloading 
of  one  round  by  decreasing  the  loath'd  (piantity  by  one  and  increasing  the  requested  transfer 
quantity  by  one.  Invoke  libsupplies  to  increment  the  munition  amount  in  the  storage  area  by 
one  round.  If  the  requested  tran.sfer  quantity  has  increased  to  zero,  set  the  loading  state  to 
BALGUN.LOADING.STATE.IDLE.  otherwise  reset  the  loader  time  back  to  the  load  time  of  the 
configuration  file. 

•  If  the  loading  state  is  not  one  of  those  named  above,  print  an  error  message  and  set  the  loading 
state  to  BALGUN.LOADING.STATE.IDLE. 


2.3  bgun.tracker.tick 

The  processing  for  bgun.tracker.tick  is  as  follows: 

1.  Get  the  physical  limits  (the  ele\'ation  up  limit  and  down  limit)  and  the  turret  name  for  this 
gun. 

2.  The  gun’s  physical  elevation  needs  to  be  updated  based  on  the  projected  elevation  and  rate 

of  the  previous  tick  plus  dT  (the  time  between  ticks).  Since  the  projected  elevation  and  rate 
of  the  previous  tick  are  recorded  in  the  last  vehicle  appearance  packet,  retrieve  them  via  a 
libentity  call.  The  new  physical  ^|e^-ation  is  the  sum  of  the  retrieved  elevation  plus  the  change 
in  elevation  this  tick.  That  change  is  calculated  by  multiplying  the  retrieved  elevation  rate 
by  dT.  Test  whether  the  new  elevation  needs  to  be  clipped  to  keep  the  gun  elevation  within 
limits.  If  clipping  is  needed,  deierniiue  the  elevation  direction  (up  or  down)  and  then  clip  to 
the  appropriate  limit.  This  hamih's  the  case  when  a  long  time  between  times  could  permit  a 
gun  to  go  completely  past  a  ttupiinig  (Miiui.  Clipping  causes  a  discontinuity  in  elevation  and 
requires  a  resetting  of  the  elevation  rate  to  zero.  Call  libentity  to  pass  it  the  new 

elevation. 

3.  Set  the  new  elevation  rate  i.ti  t!ie  retrieved  elevation  rate.  Clip  the  rate,  if  necessary,  to 
keep  the  rate  within  the  limit'  iii<>d  m  the  configuration  file.  Call  libentity  to  pass  it  the 
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new  elevation  rate. 

4.  If  the  tracking  mode  is  BALGUN_TRACKING.MODE_MANUAL,  the  gun  will  use  the  elevation  that  tlie 
user  asks  for  rather  than  a  requested  tracking  elevation.  Therefore,  set  the  gun’s  turret_requost 
field  to  FALSE  and  set  turret.at. desired  to  FALSE. 

5.  If  the  tracking  mode  is  BALGUN.TRACKING_MODE_TARGET,  retrieve  the  location  of  the  requestc»| 
tracking  target  via  a  caU  to  libentity.  Use  the  same  code  as  that  used  for 
BALGUN_TRACKIHG_MODE_LOCATION  to  calculate  a  tracking  azimuth  and  tracking  elevation. 

6.  If  the  tracking  mode  is  BALGUN.TRACKING.MODE.LOCATION  or 
BALGUN_TRACKING_MODE_LOCATION,  a  requested  azimuth  and  a  requested  elevation  must  be 
calculated.  First,  retrieve  the  location  and  azimuth  of  the  gun’s  vehicle  via  calls  to  libentity. 
Using  the  position  data,  calculate  a  vector  between  the  simulated  vehicle  and  the  requested 
tracking  location.  Using  the  vehicle’s  azimuth,  calculate  the  position  to  shoot  at  in  hull  coor¬ 
dinates.  The  desired  elevation  and  desired  azimuth  can  then  be  determined  using  an  asin,  an 
atan2,  and  a  sqrt.  The  azimuth  calculation  is  an  atan2.  The  elevation  calculation  is  done  by 
first  calculating  the  3D  range  (which  can  be  used  later  as  input  to  the  Fire  PDU),  and  using 
an  asin  on  the  Z  linear  elevation  in  vehicle  hull  coordinates  with  respect  to  this  3D  range.  Note 
that  a  less  useful  way  of  calculating  this  elevation  is  with  an  atan2  on  Z  with  respect  to  the 
distance  in  the  XY  plane,  but  this  doesn't  give  the  more  useful  3D  range  as  a  side-effect.  Since 
the  gun  is  in  a  tracking  mode,  it  is  necessary  to  note  whether  the  turret  mairi tains  the  requested 
tracking  azimuth.  When  it  doesn’t,  turret.at.desired  is  set  to  FALSE.  This  setting  will  be 
used  in  the  tests  that  determine  the  gun's  tracking  status.  When  the  turret  is  not  at  the  gun’s 
requested  azimuth,  set  the  gun’s  turret  j-equest  field  to  TRUE  and  invoke  a  turret  component 
macro  to  call  a  libgenturret  function  that  simulates  the  moving  of  the  turret  to  the  requested 
azimuth.  If  the  turret  is  at  the  gun’s  requested  azimuth,  then  set  the  gun’s  turret  j«quest  field 
to  FALSE  to  indicate  that  this  tracked  gun  is  pointing  at  the  proper  location  and  does  not 
need  to  request  that  the  turret  rotate. 

7.  If  the  gun’s  tracking  mode  is  not  one  of  the  valid  modes  (BALGUN.TRACKING.MODE.HANUAL, 
BALGU1(_TRACKING„N0DE_MANUAL,  or  BALGUN_TRACKING_MODE_MANUAL)  print  an  error  message, 
and  set  the  mode  to  BALGUN.TRACKING.HODE_MANUAL. 

8.  Adjust  the  requested  elevation  to  make  sure  it  does  not  exceed  the  gun’s  up  or  down  limits. 

9.  Calculate  dE  (the  change  in  distance  to  reach  the  requested  elevation).  If  the  gun  is  already 
close  enough  to  the  requested  elevation  (within  1.5  degrees)  and  the  elevation  rate  is  very  slow 
(less  than  or  equal  to  1.5  degrees/sec)  consider  the  gun  to  be  at  the  requested  elevation  and 
set  the  elevation  rate  to  0  degrees/second. 

10.  When  the  gun  arrives  at  the  requested  elevation,  set  the  gun’s  atjdesired  field  to  TRUE  and 
call  libentity  to  update  the  gun  elevation  and  elevation  rate  in  the  vehicle  appearance  packet. 

11.  If  the  gun  has  not  yet  arrived  at  the  requested  elevation,  set  a  new  elevation  rate  and  set  the 
gun’s  atjdesired  field  to  FALSE.  This  FALSE  setting  will  be  used  in  tests  that  determine  the 
gun’s  tracking  status.  The  new  elevation  rate  is  an  adjustment  that  takes  into  account  the  size 
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of  the  d£  (elevation  change)  and  the  how  often  this  tracker  code  ticks. 

12.  The  tracking  phase  begins  when  a  target  js  defined,  and  the  gun  and  turret  are  first  pointed 
at  the  desired  location.  This  event  is  synonomous  with  the  vehicle  commander  giving  the 
command  "Gunner".  The  sense,  detect,  recognize,  and  identify  steps  have  already  taken 
place.  The  coarse  lay  of  the  gun  has  not  yet  taken  place.  The  length  of  the  tracking  phase  is 
defined  by  bgun..get_tracktime,  which  considers  the  firer’s  and  target’s  velocities,  the  range  to 
the  target,  and  whether  this  is  the  firer’s  first  shot  at  this  target. 

13.  The  tracktime  table  for  the  loaded  munition  contains  factors  for  moving  firer  and  moving 
target.  The  factors  for  the  stationary  condition  are  1.  The  overall  factor  F  is  the  product 
of  the  firer  and  target  factors.  The  tracktime  table  also  contains  median  and  fixed  times 
versus  range.  A  median  M  defines  a  lognormal  distribution,  where  the  logs  of  the  values  are 
normally  distributed  with  a  standard  deviation  of  0.5,  and  the  median  of  the  actual  values 
is  M.  The  tracktime  for  the  firer’s  first  shot  at  a  target  and  the  firer’s  subsequent  shots  at  a 
target  are  ^ven  by:  first  tracktime  =  (  F  *  lognormal(m=ffirejnedian)  )  sub.  tracktimes  =  ( 
F  *  lognormal(m=sfire_median) )  +  sfireJlxed 

14.  After  the  tracking  period  has  elapsed,  the  gun  considered  "tracked"  (indicated  by  its  traicking 
field  set  at  TRUE).  If  the  gun  is  loaded,  the  gun  can  be  fired. 

15.  Any  successive  ticks  while  the  tracking  field  is  set  at  TRUE,  will  test  whether  a  loss  of  tracking 
occurs  because  the  gun  and  turret  are  not  still  where  they  are  supposed  to  be. 


2.3.1  bgun-iirer.tick 

The  processing  for  bguii.firar.tick  is  as  follows: 

1.  If  this  gun  does  not  have  a  fire  request  (either  an  at-target  or  an  at-location  request),  exit. 

2.  If  the  gun  has  ammunition  loaded  and  its  loading  state  is  idle  (rather  than  loading  or  unload¬ 
ing),  then  continue.  Otherwise,  set  the  fire  requests  to  FALSE  and  exit. 

3.  If  the  gun  can  not  fire  because  of  pending  firing  going  on  from  a  previous  burst,  exit. 

4.  If  the  loaded  quantity  is  less  then  the  firing  request  quantity,  clip  the  firing  request  quantity 
down  to  the  loaded  quantity. 

5.  Get  munition  specifics,  such  as  the  loaded  munition  type,  from  the  gun’s  munition  table. 

6.  If  the  request  is  a  fire  at-target  request,  reset  the  requests  to  FALSE.  If  this  gun  is  tracked 
and  its  tracking  mode  is  BALGUN_TRACKING.HODE.TARGET,  compare  the  requested  firing  tar¬ 
get  to  the  requested  tracking  target.  If  the  two  targets  are  different  invoke  the  function 
shoot.at.pointing  to  calculate  the  location  the  gun  is  pointing  at  (this  function  is  described 
later).  If  the  two  targets  are  the  same,  then  test  for  visibility  to  the  target  location  via  a  call  to 
bgun.target.int«r8ection.  This  function  will  invoke  the  SENSORS.GET.TARGET. VISIBILITY 
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macro  to  determine  if  it  would  be  possible  for  the  gun  to  hit  thtt^  target.  When  there  isn’t  vis¬ 
ibility,  this  function  will  return  an  intermediate  vehicle  or  location  to  which  there  is  visibility. 
If  there  is  visibility,  shoot  the  target  via  the  function  bgxm_shoot_to_hit.vahicle;  otherwise 
shoot  the  intermediate  vehicle  or  location  via  the  function  bgim_shoot_int«xB«dlat«. 

7.  If  the  request  is  a  fire  at-location  request,  reset  the  requests  to  FALSE.  If  this  gun  is  tracked 
and  its  tracking  mode  is  BALGUN_TRACKING_MOOE_LOCATION,  compare  the  requested  firing  lo¬ 
cation  to  the  requested  tracking  location.  If  the  two  locations  are  different  invoke  the  function 
shoot.at.pointing  to  calculate  the  location  the  gun  is  pointing  at  (this  function  is  described 
later).  If  the  two  targets  are  the  same,  then  test  for  visibility  to  the  target  location  via  a  call  to 
bgiin_location.intersact.  This  function  will  invoke  the  SENSORS.GET.LOCATION. VISIBILITY 
macro  to  determine  if  it  would  be  possible  for  the  gun  to  hit  a  3.0  X  3.0  meter  cube  at  the 
target  location.  When  there  isn’t  visibility,  this  function  will  set  an  intermediate  vehicle  or 
location  to  which  there  is  visibility.  If  there  is  visibility,  shoot  the  location  via  the  function 
bgun.8hoot_to_hit_location;  otherwise  shoot  the  intermediate  vehicle  or  location  via  the 
function  bgun_8hoot_intarmadiate. 

8.  Subtract  the  fired  quantity  from  the  loaded  quantity. 

9.  Increment  the  next  shot  time  by  the  time  necessary  to  handle  this  request.  This  is  determined 
by  the  rate  in  the  munition  table. 


2.4  Firing  Event  Processing 

The  following  functions  handle  the  firing  event  processing  of  Ubbalgun. 


2.4.1  bgun_slioot_to_hit_location 


The  function: 


bgun.8hoot.to_hlt.location(v«hicle_id ,U88r_data_handle , 

location,  gun,  nnm_table) 


does  the  following: 


1.  Gets  the  location  of  the  shooting  vehicle  plus  the  burst  specifics  (location). 

2.  Calculates  the  range  and  time  of  burst. 

3.  Calls  the  function  8«nd_balli8tic.fire  to  build  and  send  a  Fire  PDU. 
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4.  Schedules  an  Impact  PDU  via  a  deferred  function  call  of  send.balli8tic_inq>act.  The  Impact 
packet  will  be  sent  in  accordance  with  the  calculated  burst  time. 


2.4.2  bgun_shoot_to_hit_vehicle 
The  function: 

bgun.shoot_to_hit_v«hicle ( vehicle.id ,  user.data.handle . 

target.id,  gun,  mim_table) 


does  the  following: 

1.  Gets  the  location  of  the  shooting  vehicle  plus  the  burst  specifics  (location). 

2.  Performs  the  range  and  time  of  burst  calculations. 

3.  Calls  the  function  8end_ballistic_fir«  to  build  and  send  a  Fire  PDU. 

4.  Computes  either  a  hit  or  miss  based  on  the  gun’s  hit  probability  tables. 

5.  If  the  shot  is  determined  to  be  a  hit,  schedules  an  Impact  PDU  via  a  deferred  function  call  of 
sendLballlstic.iiqiact.  The  Impact  packet  will  be  sent  in  accordance  with  the  calculated 
burst  time. 

6.  If  the  shot  is  determined  to  be  a  miss,  computes  a  miss  position  as  being  between  3  and  8  meters 
directly  short  of  the  target  and  then  schedules  an  Impact  PDU  via  a  deferred  function  call  of 
8end_balli8tic_l]itpact.  The  Impact  packet  will  be  sent  in  accordance  with  the  calculated 
burst  time. 


2.4.3  bgun_shoot_intermediate 


The  function: 


bgun_8hoot.intaxBadiate (vehicle.id,  user.data.handle ,  gun, 

int.location,  int. vehicle,  mun. table) 


does  the  following: 


1.  Gets  the  location  of  the  shooting  vehicle. 

2.  Updates  the  gun’s  derived  quantities  (vector  and  range)  to  accommodate  the  different  location. 


Chapter  2:  Algorithms 


13 


3.  Calls  bg\m_8hoot_to_hit_location  if  this  is  a  shot  to  the  ground  (or  building)  or  if  the 
configuration  file  has  the  hit.obscuring. vehicles  parameter  set  to  FALSE. 

4.  Calls  bgun_8hoot_to_hit_vehicle  if  this  is  a  shot  to  an  intermediate  vehicle. 

2.4.4  shoot.at.pointing 

Libbalgun  makes  use  of  the  function  shoot.at.pointing  when  the  gun  wants  to  shoot  but  is 
not  pointing  where  it  should  be.  To  haiullo  this  fall  through  case,  an  alternate  location  is  calculated 
and  shot  at  with  the  following  steps: 

1.  Calculate  a  location  that  the  gun  is  pointing  at  that  is  no  further  away  from  the  gun  than  the 
loaded  munition’s  maximum  range  will  permit. 

2.  Test  visibility  to  that  point. 

3.  If  the  gun  has  visibility  to  that  maximum  range  point,  place  the  round  on  the  ground  at  that  lo¬ 
cation  via  a  call  to  bgim.8hoot.to.hit.location,  otherwise  place  the  round  at  somewhere  or 
something  in  between  the  gun  and  t  he  max  range  location  via  a  call  to  bgun_8hoot.inteziii8diat8. 
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3  Exam  pies 


To  get  the  component  number  of  a  gun  with  a  particular  name  (such  as  "main-gun"): 


int32  gun; 

if  ((gun  ■  CBipnt_locate(Tehicle_id,  name))  >■ 

CMPMT.IIOT.FOUHD) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  gun  called  \"Xs\".\n", 
vehicle. id. 
name) ; 


To  then  give  a  command  to  that  gun  (the  macro  is  defined  by  libguns;  it  assembles  a  GUNS.INTERFACE 
structure,  and  calls  copnt.invoke): 


if  (gun  !-  CMPVT.HOT.FOUin)) 
GUMS.SET.ELEVATIOKvehicle.id,  gun,  elevation); 
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4  Functions 


The  following  sections  describe  each  function  provided  by  libbalgun,  including  the  format  and 
meaning  of  its  arguments,  amd  the  meaning  of  its  return  values  (if  any). 


4.1  bgunJnit 


void  bgpin.init (packet. valve,  event.id,  sia.addr,  protocol, 
data_path,  flags) 

PV_VALVE_PTR  packet. valve; 

int32  *event_id: 

SisnilatlonAddress  *aim.addr; 
int32  protocol ; 

char  *data.path: 

uint32  flags ; 

‘packet. valve’ 

Specifies  the  packet  valve  used  to  send  fire  and  impact  pdus 

‘event.id’ 

Specifies  a  pointer  to  a  static  host  event  counter 

‘si]B.addr’ 

Specifies  simulation  address  for  outgoing  event  DIS  IDs 

‘protocol’ 

Specifies  protocol  in  use  (0  for  SIMNET,  DIS.P110T0C0L.VERSI0H.*  for  DIS) 

‘flags’  libreader  flags  to  pass  to  reader.readO  (see  section  ‘reader .read’  in  LibReader 
Programmer’s  Manual)  when  hit  table  files  are  read 


bgun_init  initializes  libbalgun.  Call  this  before  any  other  libbalgun  function. 


4.2  bgun .class Jnit 

void  bgun.clasB.init(parent.class) 
CLASS.PTR  parent.class ; 


‘parsnt.class’ 

Class  of  the  parent  (declared  with  class.declara.class) 
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bgun.class.init  creates  a  handle  for  attaching  balgun  class  information  to  vehicles.  The 
parent. class  will  likely  be  safobj. class. 


4.3  bgun.tick 


void  bgun.tick(vehicle.id.  ctdb) 
int  vehicle.id; 

CTDB  *ctdb: 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘ctdb’  Specifies  the  terrain  database 

bgun.tick  ticks  the  gpins  for  a  vehicle,  ctdb  is  required  in  order  to  access  terrain  information 
for  shooting  misses. 


4.4  bgun.component..AV«ilability 


void  bgun.coaq)onent.availability(vehicle.id.  conponent,  is.available) 
int32  vehicle.id; 
int32  coi^nent; 
int32  is.available: 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘component’ 

Specifies  a  component  which  has  changed  availability 
‘is.available’ 

Specifies  whether  the  component  is  available  or  not 

bgun.component_availability  inforiiui  a  vehicle’s  balguns  about  a  change  in  status  for  com¬ 
ponents.  If  a  component  that  a  iMlgun  i»  using,  (such  as  the  turret  that  the  gun  is  attached  to) 
becomes  unavailable,  the  gun  IxviitiM's  unavaiiable. 


4.5  bgun .damage 
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void  bgun_daBage (vehicle. id,  damage) 
int32  vehicle.id; 
int32  damage: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘damage’  Specifies  whether  the  gun  is  damaged.  When  the  function  is  invoked  with  damage 
set  to  TRUE,  the  gun  state  will  be  set  to  BALGUN.STATE.DESTROYEO  and  libentity 
will  be  invoked  to  set  the  gun  elevation  value  to  -0.3.  When  the  function  is  in¬ 
voked  with  damage  set  to  FALSE,  a  destroyed  gun  will  have  its  the  gun  state  reset 
to  BALGUN.STATE. HEALTHY  and  libentity  will  be  invoked  to  reset  the  elevation  value  to 
0.0. 

bgun.damaga  informs  a  vehicle’s  balguns  about  whether  they  should  be  damaged  or  not.  This 
is  used  to  model  external  damage  assessment. 
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1  O  verview 


Libc2obj  provides  the  class  superstructure  in  which  all  command-and-control  sub-classes  reside. 
Examples  of  these  sub-classes  include:  unit,  graphics,  task,  task  frame,  and  unitorg.  They  can  be 
thought  of  as  the  pieces  that  make  up  the  c2obj  class. 

Various  libraries  define  classes  of  objects  which  are  instantiated.  Most  notably:  LibPO  creates 
line  graphics,  units,  task  frames,  etc.  Often  the  same  object  is  represented  in  two  ways,  once  at  a 
low  software  layer,  and  again  in  a  higher  layer.  For  example: 

Object  Type  Lo«- Layer  Representation  High- Layer  Representation 

route  (line  graphic)  libpo  persistent  object  libc2obj  object 

For  each  class  of  object,  there  is  a  senior  layer  (libc2obj)  responsible  for  management  of  that 
class.  This  will  generally  not  be  the  layer  which  instantiates  the  objects  (libpo).  Hence  for  persistent 
object  classes: 

High  layer  libc2obj 
Mid  layers 

libunits,  libgraphics,  libtaskframe,... 

Low  layer  libpo 

Instances  of  the  c2obj  class  are  attached  as  user  data  to  Persistent  Objects  of  various  classes 
such  as  the  line  class,  the  point  class,  and  the  unit  class  (e.g.  see  section  ‘Unit  Class’  in  LibPO 
Programmer’s  Guide). 

Libc2obj  registers  a 

nev.obj act. event. handler  (see  section  ‘newjobjectjeventJiandler’  in  LibPO  Programmer’s  Guide) 
and  an  object.gone.event. handler  (see  section  ‘object,gone_eventJiandler’  in  LibPO  Program¬ 
mer’s  Guide)  in  the  PO  database  to  cause  the  creation  and  destruction  of  c2obj  instances  when 
new  PO  objects  are  received  or  old  PO  objects  are  destroyed.  For  example,  when  a  user  at  a 
SAFstation  creates  a  new  unit,  the  resulting  newjobjectjeventJiandler  instructs  LibPO  to  build  an 
instance  of  the  unit  class  in  the  PO  database.  When  a  user  deletes  an  existing  point  graphic  from 
the  SAFSstation,  the  resulting  object,gone.event Jiandler  instructs  libpo  to  remove  the  instance  of 
the  point  class  in  the  PO  database. 


Adding  a  sub-class  requires  making  the  following  changes  to  this  library: 
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1.  Modify  c2obj_init  to  initialize  the  sub-class. 

2.  Modify  c2obj_create  to  create  the  sub-class  at  the  appropriate  point  (after  those  sub-classes 
in  lower  layers,  and  before  those  in  higher  layers). 

3.  Modify  c2obj_destroy  to  also  destroy  the  new  sub-class. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libc2obj,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  c2objJnit 

void  c2obj_init(db) 
PO.DATABASE  *db: 


c2obj_init  initializes  libc2obj.  Call  this  before  any  other  libc2obj  function.  Note  that  this 
function  will  call  the  '^jclassJnit  routines  for  all  c2obj  subclasses.  Hence,  yon  should  call  their 
primary  init  routines  before  c2obj_init. 


f 
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1  O  vervie w 


Information  can  be  classified  into  two  categories:  state  and  events.  State  information  is  present 
at  all  times,  and  describes  things  like  the  location  of  a  vehicle,  or  the  name  of  the  mission  being 
executed.  State  information  can  be  easily  controlled  and  made  available  to  all  software  modules 
using  the  ModSAF  data  hiding/sharing  techniques  (see  the  ModSAF  methodology  documentation 
in  the  ModSAF  Programmer’s  Guide  for  more  on  this  subject).  Events  are  one  time  occurrences  in 
the  simulation,  such  as  the  explosion  of  an  artillery  shell.  Often,  it  is  convenient  to  treat  a  change 
of  state  as  an  event,  such  as  when  a  vehicles  runs  out  of  fuel  (the  value  of  the  fuel  state  variable 
changed  to  zero). 

Sharing  event  information  is  problematic.  The  most  common  method  used  in  real  time  sim¬ 
ulation,  is  strict  function  chaining:  when  event  ’X’  happens,  function  ’Y’  will  be  called.  To  add 
another  consequence  to  event  ’X’  requires  that  function  ’Y’  be  changed.  This  causes  interoperability 
problems,  and  may  make  layering  of  software  impossible. 

An  alternative  method  of  event  handling  is  through  the  use  of  "callback"  functions.  A  software 
module  which  is  interested  in  an  event,  requests  that  the  software  module  generating  that  event 
call  a  function  when  the  event  happens.  If  the  software  can  only  register  one  callback  function, 
however,  this  solution  is  little  better  than  hard  coding  responses  to  events.  What  is  needed  is  a 
way  for  an  arbitrary  number  of  software  modules  to  re^ster  event  handlers,  such  that  all  of  them 
may  be  called. 

X  windows  provides  callback  functionality  using  an  extremely  flexible  (and  consequently,  very 
computationally  expensive)  method.  Events  are  identified  by  name  (a  character  string),  and  are 
uniquely  tied  to  an  object  (e.g.,  pressing  a  button  on  the  screen  generates  an  event,  pressing  a 
different  button  generates  a  different  event);  software  modules  can  register  callback  routines  by 
specifying  the  object  involved  and  the  name  of  the  event.  No  distinction  is  made  between  private 
and  public  events.  No  facility  exists  for  registering  object-independent  callback  functions  (a  software 
module  must  re-register  the  callback  function  with  every  object  to  make  it  apply  to  all  of  them). 

Libcallback  implements  a  similar  functionality  with  a  simple,  real  time  technique.  A  software 
module  registers  an  event  with  libcallback,  giving  the  types  and  order  of  arguments  (libcallback 
will  need  this  information  later);  note  that  no  name  is  ^ven.  Libcallback  returns  a  handle  to 
the  software  module,  which  the  module  may  either  make  public,  or  keep  private.  Other  software 
modules  may  register  callback  routines  which  are  associated  with  this  event  handle,  along  with  a 
constant  which  it  requests  be  passed  as  the  last  argument  (this  allows  the  receiver  to  define  one 
callback  function  to  be  used  with  a  variety  of  similar  events).  When  the  event  occurs,  the  software 
generating  the  event  passes  libcallback  the  event  handle  and  arguments;  libcallback  then  calls  all 
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registered  callback  routines  (the  order  of  calling  is  not  guaranteed,  and  cannot  be  depended  upon). 

A  software  module  may  create  a  unique  event  for  each  object  created  (as  in  X  windows),  or  it 
may  create  one  event  for  an  entire  class  of  objects  (such  as  the  PO  database  object_changed  event). 
Unlike  X,  the  number  and  type  of  arguments  are  defined  on  a  per-event  basis  (X  has  a  standard 
set  of  three  arguments  which  are  passed  to  every  callback  routine). 

The  use  of  libcaUback  for  distribution  of  events  is  not  always  appropriate.  In  general,  libcallback 
should  be  only  be  used  to  distribute  event  information  from  low  layer  service  providers  (such  as 
Ubpo  or  libvtab)  to  high  layer  independent  object  classes  (such  as  libdfdam  and  libtactmap).  The 
use  of  libcallback  for  distribution  of  events  within  an  object  is  strongly  discouraged;  direct  function 
invocation  should  be  used  instead.  I'he  problem  here  is  that  a  renegade  programmer  can  use 
libcallback  to  violate  normal  layering  constraints.  Consider  the  following  examples: 

Example  1:  Proper  use  of  libcallback 

Indirect  fire  appears  on  the  network  in  the  form  of  a  DIS  PDU.  A  low  layer  service  provider  (such 
as  libpktvalve)  receives  this  PDU  and  must  distribute  the  indirect  fire  event  to  all  interested  high 
layer  object  classes.  One  of  these  classes  is  the  local  vehicle  simulation  (which  evaluates  damage 
from  indirect  fire).  Another  is  the  map  display  system  (which  draws  indirect  fire  on  the  map).  One 
or  both  of  these  classes  may  appear  in  the  simulation,  depending  upon  how  the  program  is  linked 
(as  a  SAFSIM,  SAFSTATION,  or  POCKET  SAF). 


Libcallback  provides  a  useful  service  in  this  case.  The  generator  of  the  event  is  in  a  low  layer, 
and  is  not  part  of  either  receiver  class  ( vehicle  simulation,  or  map  display).  The  receiving  classes 
are  in  high  layers,  are  completely  independent,  and  may  or  may  not  appear  in  the  same  executable 
system. 

Example  2:  Improper  user  of  libcallback 

The  physical  simulation  of  a  vehicle  (e.g.,  libtracked)  determines  that  the  vehicle  has  run  out  of 
fuel.  Running  out  of  gas  may  trigger  levrral  responses  within  the  vehicle.  There  are  three  options 
for  sharing  the  out-of-gas  event: 

1.  The  class  which  inherits  libtra*  k«*<l  g..  safobj  class)  may  poll  a  public  state  variable  within 

the  libtracked  class  to  doi<*riiMi,<-  if  tho  event  has  occurred. 

2.  Libtracked  may  provide  a  '«  r'.  .<  lU  <>tiperior  class,  in  the  form  of  a  callback  function  passed 

in  at  initialization,  and  cal!>  •:  ^  ‘  •  !,f  \ehicle  runs  out  of  fuel.  The  superior  class  would  then 

call  appropriate  function.^  iti  .i.l  t«’d  subsystems. 
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3.  Libtracked  can  define  an  event  via  libcallback,  and  all  other  subsystems  of  the  vehicle  which 
respond  to  running  out  of  fuel  can  register  handlers  for  this  event. 

The  first  option  is  undesirable  because  it  is  both  inefficient  and  requires  making  public  state 
which  could  otherwise  be  kept  private.  Hence,  the  only  decision  is  between  the  second  and  third 
options.  Consider  the  following  attributes: 

Layering  In  option  2,  the  libtracked  layer  provides  a  service  to  the  safobj  class  (telling  it  the 
vehicle  just  ran  out  of  fuel).  Each  other  subsystem  also  provides  services  to  the  safobj 
(responding  appropriately  to  running  out  of  fuel).  Hence,  layering  is  ensured. 

In  option  3,  libtracked  provides  a  service  to  all  subsystems.  Since  some  subsystems 
can  be  in  higher  layers  than  libtracked,  and  others  in  lower  layers,  layering  cannot  be 
guaranteed.  Put  another  way,  option  3  guarantees,  that  given  enough  time,  someone 
WILL  violate  layering. 

Specification 

In  option  2,  each  service  (the  out-of-gas  notification,  and  each  out-of-gas  reaction)  is 
specified.  That  a  callback  is  provided  by  libtracked  is  specified  in  its  initialization 
routine;  the  other  subsystem  reaction  functions  are  each  specified  as  available  public 
function  calls. 

In  option  3,  only  the  eidstence  of  the  event  is  specified.  The  subsystems  which  respond 
to  this  event  can  only  be  discovered  by  an  examination  of  the  software. 

Clarity  In  option  2,  safobj  will  contain  a  function  which  calls  aU  the  subsystenos  which  respond 
to  running  out  of  fuel.  The  order  will  be  explicit,  and  interactions  between  subsystems 
will  be  predictable. 

In  option  3,  the  order  in  which  subsystems  react  to  running  out  of  fuel  cannot  be 
predicted,  and  the  interactions  between  subsystems  can  only  be  found  through  experi¬ 
mentation  or  detailed  analysis. 

Given  these  considerations,  it  is  clear  that  libcallback  is  less  desirable  than  using  an  explicit 
callback  within  libtracked.  The  problem  can  be  summarized  succinctly:  libtracked  is  in  too  high  a 
layer  for  libcallback  to  be  useful. 
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2  Examples 


The  following  program  demonstrates  the  use  of  libcallback  functions.  This  prc^ram  appears  as 
‘test.c’  in  the  libcallback  source  directory,  and  can  be  compiled  with  the  command  ^nake  test’. 


/*  Include  these  header  files  in  any  file  using  libcallback  functions  */ 
iinclude  <libcallback.h> 

iinclude  <stdext.h>  /*connon/ include/global*/ 

/*  This  test  prograa  deoonstrates  a  callback  relationship  betveen 

*  three  libraries:  (1)  A  network  interface  library  vhich  is  detecting 

*  direct-  and  indirect-fire  events;  (2)  A  simulation  library  vhich 

*  queues  these  events  for  vehicle  processing;  (3)  A  display  library 

*  vhich  draws  effects  on  a  map. 

* 

*  The  network  library  defines  the  event,  and  puts  the  handle  in  a 

*  public  variable.  The  other  libraries  know  where  to  find  the  handle 

*  and  the  format  of  the  event  from  the  docximentation  of  the  network 

*  library;  they  attach  their  handlers. 

* 

*  Note  that  while  the  simulation  ttses  two  different  handlers,  the 

*  display  routine  uses  only  one  handler  and  discriminates  via  the  user 

*  data.  The  latter  is  OK  only  if  the  events  have  the  same  number/types 

*  of  arguments  (in  this  case  DOUBLE,  PTR). 

•/ 


/****0mm*************************m************m********m**mm*m***/ 
/*  Network  Library  */ 


CALLBACK.EVEIT.PTR  df.event.handle; 

CALLBACK.EVENT.PTR  if.event_handle; 

void  network. initC) 

{ 

df.event.handle  ■  callback.define.event(A_DOUBLE,  A_PTR,  A_EMD); 
if. event. handle  >  callback.define.event(A.DOUBLE,  A.PTR,  A.EHD); 

> 

void  netvork.detect.df (when,  data) 
float64  when; 
char  edata; 

callback.fire.event(df.evant.handle,  when,  data); 

} 


void  netvork.detect.if (when,  data) 
floated  when; 
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char  *data; 

< 

callback.fire_«vent(if.«vent.handle,  whan,  data); 

} 


/*  Sinulation  Library  */ 


/*  fincluda  network  public  header  */ 

void  distribute.df (when,  data,  ignored) 
float64  when; 
char  *data: 

ADDRESS  ignored; 

•C 

/*  allocate  buffers  and  queue  for  vehicle  processing. . .  •/ 
printf ("Simulation:  df  at  Xf  <Xs>\n",  when,  data); 

} 

void  distribute.if (when,  data,  ignored) 
float64  when; 
char  edata; 

ADDRESS  ignored; 

i 

/*  allocate  buffers  and  queue  for  vehicle  processing. . .  */ 
printf ("Simulation;  if  at  Xf  <Xs>\n",  when,  data); 


void  simulation.init() 

callback.register.handler (df .event.handle ,  distribute.df , 

©/♦Ignored*/) ; 

callback_register_handler(if .event.handle,  distribute.if, 

©/♦Ignored*/) ; 


/*•****•*•*•***.*******************,***,*,***,***„***.****„**„, 

/*  Display  Library  ♦/ 


/♦  tinclude  network  public  header  ♦/ 

•define  DF.TYPE  1 
•define  IF.TYPE  2 

void  display.df.or.if (when,  data,  what) 
float64  when; 
char  *data; 

ADDRESS  what; 

{ 
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svitchC (int32) ehat) 

■C 

case  DF.TYPE: 

printf ("Display:  df  at  <y,8>\n",  when,  data); 

break; 

case  IF.TYPE: 

printf  ("Display :  if  at  y.f  <y8>\n",  when,  data); 

break; 

} 

} 


void  display.initO 

< 

callback_regi8ter_handler(df_event„handle,  display.df.or.if , 

DF.TYPE) : 

callback_regi8tar_handler(if.event_handla,  display.df.or.if , 

IF.TYPE) : 


} 


void  display.no.if () 

■C 


> 


callback_unregi8ter_handlar(if_event.handle,  display.df.or.if, 

IF.TYPE) ; 


void  di8play.if.too.much() 
int32  i; 


} 


f or(iaO ; i<10 ; i++) 

callback_regi8ter.handlar(if .event.handle ,  display.df.or.if , 

IF.TYPE) ; 


/***ee«**«e**«e*e*«e„,*„,«w,««,*««**«*,««****»«*«««,,««***,,,,**„*,**/ 

aiainO 

{ 

/*  Initialize  the  libraries.  Note  that  the  library  which  defines 
*  the  event  must  be  initialized  first. 

*/ 

network.  initO ; 

8ifflulation.init() ; 
display.initO ; 

/*  Trigger  some  events  •/ 
network. detect. df (1.0,  ' Bang") ; 
network.detect.if (2.0,  Boom"); 
network.detect.df (3.0,  Pow" ) ; 
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/*  Disabla  th«  display  of  indirect  fire  */ 
display.no.if 0 ; 

/*  Trigger  some  events  */ 
network_detect_df (4.0,  "Bang"); 
network.detect.if (5.0,  "Boom") ; 
network_detect_df (6.0,  "Pow"); 

/*  Add  a  ehole  brmch  of  callbacks  */ 
display.if.too.muchO ; 

/*  Trigger  some  events  */ 
netTOrk.detect_df (4.0,  "Bang"); 
nat«ork_detect_if (5.0,  "Boom") ; 
netffork_datect_df (6.0,  "Pow"); 

/•  Disable  the  if  display  again  */ 
display.no.if () ; 

/*  Trigger  some  events  */ 
net«ork.detect.df (7.0,  "Bang"); 
nat«ork_datect_if (8.0,  "Boom"); 
network_detect.df(9.0,  "Pow"); 

/*  Clean  up  and  exit  */ 
callback.destroy .event (df .event .handle) ; 
callback.de8troy.event ( if .event.handle) ; 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libcallback,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  callback_define-event 

CALLBACK.EVEirr.PTR  callback_deline.event(arg.typeO,  arg.typel . 

A_END) 

int32  arg.typeO,  arg.typel,  .... 

‘arg.t7pe8’ 

Specifies  the  types  of  the  arguments  passed  when  the  event  fires.  Chosen  from  the 
set:  AJNT,  AJ)OUBLE,  AJPTR,  AJSHORT,  AXHAR,  AFLOAT  (defined  in  com¬ 
mon/include/ global/stdext.h). 

‘A.Ein)’  Constant  which  should  always  be  passed  as  the  last  argument. 

callbackjdefinejevent  creates  an  event  and  returns  a  handle  which  can  be  used  to  register  han¬ 
dlers,  fire  the  event,  or  destroy  the  event.  The  arguments  specify  the  types  of  up  to  four  arguments 
which  will  be  passed  when  the  event  fires,  (e.g.,  callbackjdefinejevent(AJNT,  AJNT,  AJDOUBLE, 

aj:nd)). 


3.2  callback jregisterJiandler 


void  callback.register. handler (event .handle,  handler.function,  uaer.data) 
CALLBACK.EVENT.PTR  event.handle ; 

CALLBACK.HANDLER  handler.function: 
address  uaer.data; 


‘event.handle’ 

Identifies  the  event. 

‘handler.function’ 

Specifies  the  function  to  be  called  when  the  event  occurs. 

‘uaer.data’ 

Specifies  a  constant  which  will  be  passed  to  the  handler  Junction  as  the  last  argument. 
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callback_registerJiandler  notes  that  a  function  is  to  be  called  when  an  event  occurs.  The 
eventjhandle  identifies  the  event  (created  with  callback_definejevent),  the  handler  Junction  specifies 
the  address  of  the  function  which  is  to  be  called.  The  handler  function  should  expect  the  argu¬ 
ment  types  specified  when  the  event  was  created  (via  callback-definejevent),  as  well  as  a  trailing 
argument  which  is  the  constant  value  passed  here  as  user  data. 


3.3  callbackJire_event 

void  callback_fir«.«v«nt(«v«nt_handl«,  arg,  arg...) 

CALLBACK_EVEirr_PTR  event  handle; 

‘event. handle’ 

Identifies  the  event. 

‘args’  Specifies  up  to  four  arguments  to  pass  to  the  handlers. 

callbackJire_event  invokes  all  the  handlers  defined  for  the  event  in  no  particular  order  (if  order 
is  important,  libcallback  is  probably  not  the  right  solution,  see  Chapter  1  [Overview),  page  1).  The 
types  of  the  arguments  are  assumed  to  be  those  passed  to  callbackjdefinejevent  (see  Section  3.1 
[callback  define'event],  page  9). 


3.4  callback_unregister Jiandler 

void  callback_unr«gist«r.handl«r(event.handl«,  handler.ftmction,  uaar.data) 
CALLBACK.EVENT.PTR  event. handle ; 

CALLBACK_HAin}LER  handler.f unction; 

ADDRESS  user. data; 

‘event.handle’ 

Identifies  the  event. 

‘handler.function,  user.data’ 

Specifies  the  function/user jdata  pair  which  should  no  longer  be  called  when  the  event 
occurs. 

If  a  handler  for  the  event  Jiandle  passed  can  be  found  which  matches  the 
handler  Junction/user_data  passed,  callback-unregister  Jiandler  will  removed  it  the  list  of  fimctions 
called  when  the  event  is  fired. 
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3.5  callback^estroy_event 

void  callback_da8troy.evant(event..handl6) 

CALLBACK.EVENT.PTR  avant.handla; 

'avant.handla' 

Identifies  the  event. 

caUbackjdestroy_event  frees  the  memory  associated  with  the  passed  eventjiandle.  Referencing 
this  handle  after  after  a  call  to  this  function  will  probably  make  the  program  crash  (i.e.,  don’t  do 
it). 
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1  O  vervie w 


An  object  is  defined:  "An  area  in  computer  memory  that  serves  as  a  baisic  structural  unit  of 
analysis"  (Baron).  A  class  defines  the  organization  of  data  in  that  memory,  and  the  functions  which 
operate  on  a  group  of  objects  which  use  the  same  organization.  Typically  a  library  will  define  a 
single  class,  and  will  provide  functions  to  create,  destroy,  or  operate  on  objects  in  that  class. 

Often  the  same  object  is  represented  in  two  ways,  once  at  a  low  software  layer,  and  again  in  a 
higher  layer.  For  example: 

Object  Type  Low-Layer  Representation  High-Layer  Representation 

Sinulated  Entity  LibVTab  vehicle  LibSAFObj  object 

Route  LibPQ  persistent  object  LibC20bj  object 

Various  libraries  define  classes  of  objects  which  are  instantiated.  Most  notably: 

•  libpo  creates  graphics,  units,  task  frames,etc. 

•  libvtab  creates  vehicles 

•  Xt  creates  widgets 

Different  high-layer  classes  need  to  attach  different  user  data  to  these  objects.  For  example, 
when  a  route  is  created  in  libpo,  the  user  interface  software  makes  a  bunch  of  widgets  and  stuff 
which  it  wants  to  attach  as  user  data  to  the  object;  simultaneously,  the  simulation  software  wants 
to  compile  the  route  into  its  internal  format,  and  attach  that  as  user  data.  This  leads  to  an 
incompatibility  which  will  prevent  linking  the  workstation  and  simulation  software  together.  What 
is  needed  is  a  way  to  declare  at  run  time  the  number  of  pieces  of  user  data  which  will  be  attached 
to  each  class  of  object. 

Low  layer  classes  generally  allow  the  attachment  of  one  piece  of  user  data  to  eau:h  object  (this 
is  true  of  libpo,  libvtab,  and  Xt).  Libclass  provides  a  sort  of  user  data  multiplexer  service  to  allow 
each  class  (each  library)  within  an  application  to  attach  its  own  kind  of  user  data  to  each  object. 

As  shown  in  the  figure  below,  a  single  slot  is  also  provided  for  a  'global’  piece  of  user  data  to  be 
attached  to  each  block.  This  slot  is  accessed  through  functions  rather  than  the  sub-class  slots. 
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Lov  Layer 
Object 


LibClass  User  Data  Block 


>1  Global  Slot  I 

I  Debug  Info  I 


i  Subclass  User  Data  | 


I  Subclass  User  Data  I 


I  Subclass  User  Data  I 


Libclass  also  provides  functions  to  aid  in  debugging.  It  manages  run  time  modifiable  flags  which 
enable  or  disable  debugging  for  each  class,  on  both  a  global  and  a  per-instance  basis.  Furthermore, 
it  manages  'show'  routines  for  each  class,  to  aid  in  debugging. 


. I 

.  a  ...  I 

. I 

User  I 
Data — 
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2  Examples 

The  program  ‘tast.c’  in  the  libclass  source  directory  demonstrates  the  mechanics  of  using 
libclass.  It  can  be  compiled  with  the  command  ‘make  test’.  The  following  example  provides  a 
bigger  picture  of  how  libclass  is  to  be  used  in  the  ModSAF  application. 

For  each  class  of  object,  there  is  a  senior  layer  responsible  for  management  of  that  class.  This 
will  generally  not  be  the  layer  which  instantiates  the  objects.  Hence  for  persistent  object  classes: 

High  layer  libc2obj 
Mid  layers 

libunits,  libgraphics,  libtaskframe, ... 

Low  layer  libpo 

High  layer  libsafobj 
Mid  layers 

libcoUision,  libcomponents,  libentity, ... 

Low  layer  libvtab 

In  each  case,  the  low  layer  creates  the  objects  (provides  an  object  creation  service),  while  the 
high  layer  is  responsible  for  managing  all  the  other  libraries  which  need  to  attach  user  data  (and 
hence  expand  upon  the  object).  The  low-layer  representation  of  the  object  class  does  not  define 
many  functions.  In  the  case  of  persistent  objects,  the  kernel  does  have  a  lot  of  state;  in  the  case 
of  safobj’s,  there  is  next  to  none.  In  both  cases,  there  is  more  than  one  layer  between  the  high 
and  low  layers  which  contributes  state.  Furthermore,  these  libraries  differ  depending  upon  how 
the  program  is  linked  (STATION,  SIM,  POCKET).  STATION  means  that  the  application  has 
no  simulation  capabilities,  SIM  means  that  the  application  has  no  user  interface  capabilities,  and 
POCKET  means  that  the  application  has  both  user  interface  and  simulation  capabilities. 

At  initialization,  libclass  will  provides  unique  handles  by  which  classes  may  be  referenced.  For 
example,  libsafobj  will  do  the  following: 

static  CLASS.PTR  safobj. class; 

safobJ.initC. . .) 

•  •  • 

< 

safobj.class  «  class.declare.classO; 

> 
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Each  client  library  that  needs  to  attach  user  data  to  a  class  thus  declared  will  do  so  in  its 
initialization  routine  (the  senior  layer  will  pass  it  the  handle  just  allocated).  In  the  hypothetical 
examples  that  follow,  it  is  assumed  that  a  vehicle  of  the  safobj  class  has  a  "driver"  sub-layer 
(subclass). 

static  int32  driver.user.daca. handle: 

drlver_inlt( safobj .class .  . . . ) 

CLASS.PTR  safobj. class: 

•C 

driver_user_data.handle  ■ 

class.reserve.user.datafsafobj .class,  "driver",  driver.printer) ; 

•  •  • 

} 


When  an  object  of  that  class  is  instantiated,  the  most  senior  layer  asks  libclass  to  allocate  space 
for  all  the  sub-layer’s  user  data.  Each  sub-layer  allocates  its  own  user  data  in  its  instantiation 
routine,  and  asks  libclass  to  store  a  pointer  to  it. 


safobj .create ( . . . ) 


VTAB.USER.OATA.TYPE  user.data; 

/*  libvtab  provides  a  kernel  object  (referenced  via  the 

*  vehicle  id),  vith  a  user.data  slot  vhich  is  filled  in  here. 

•/ 

/*  Ask  libclass  to  allocate  space  for  all  the  pointers  *! 
user.data  ■ 

(VTAB.USEll.DATA.TYPE)class.alloc.user.data(safobj. class) ; 

/*  Store  a  pointer  to  this  apace  vith  libvtab  for  later 

*  retrieval. 

*/ 

vtab.set.vehicleCvehiele.id,  user.data) ; 


driver.createCvehicle. td .  . . . ) ; 

> 


driver.createCvehicle. : i .  . . .) 
int32  vehicle. id: 
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{ 

/*  Allocate  space  to  store  o\ir  unique  state  variables. 

*  Note  that  DRIVER_VARS  is  a  private  structure  to 

*  libdriver. 

*/ 

DRIVER. VARS  ^driver  ■  ALLOCATE.DRIVER_VARS() ; 

class_set_uaer_data(vtab_get_vehicle(vehicle_id) . 

driver. user.data_handle , 
driver) : 


} 


Thereafter,  routines  which  need  to  access  their  class  variables  will  get  them  from  libclass: 


void  driver.do.somethingC vehicle. id,  ...) 
int32  vehicle.id; 

DRIVER.VARS  edriver  «  (DRIVER.VARS  *) 

class.get.user.dataCvtab.get.vehicleCvehicle.id), 

driver.user.data.handle) ; 

if  (! driver)  /*  Passive  error  detection  */ 
return; 

. . .  operate  on  driver  . . . 

> 


Note  that  both  got  routines  are  macros,  so  the  code  here  is  really  just  doing  array  references. 
Furthermore,  the  mess  of  code  making  up  the  first  three  lines  of  the  function  will  be  the  same  for 
every  functions,  and  hence  can  be  encoded  in  a  macro.  An  actual  function  should  look  more  like 
this; 


void  drivor.do.somothingCvohiclo.id,  ...) 
int32  vohiclo.id; 

GET.VARSC vohiclo.id,  drivor) ; 

if  (! driver)  /*  Passive  error  detection  */ 
return; 

. . .  operate  on  driver  . . . 

> 
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Since  all  the  pointers  to  all  the  state  structures  are  now  stored  in  a  generic  array  (allocated  by 
li^class,  and  pointed  to  by  the  user  data  elements  of  the  various  kernel  classes),  debugging  is  a 
problem,  dbx  is  not  able  to  cast  variables  for  printing,  so  examining  the  state  of  a  vehicle  would 
not  be  possible  (except  by  looking  at  the  raw  numbers  in  memory,  and  matching  them  to  structure 
members  by  hand).  The  solution  to  this  problem  is  the  debugging  information  which  was  passed 
to  libclass  at  initialization  time.  Specifically,  this  includes: 


•  A  string  which  identifies  the  name  of  the  module  ("driver",  "gunner",  ...) 

•  A  pointer  to  a  function  which  takes  a  pointer  to  the  local  data  structure,  and  will  print  its 
contents: 

static  void  driver. print (driver) 

DRIVER. VARS  •driver; 

■C 

printf ("State:  Xd  (Xs)\n",  driver->Btate, 

8tate.8tring(driver*>state)) ; 
printf ("Leader:  Xd\n".  driver->leadveh) ; 

•  •  • 

> 


With  this  information,  libclass  provides  the  class.shov  service.  This  function  can  be  called 
from  an  application  (such  as  from  a  tty  command  parser),  or  from  ‘dbx’: 


(dbx)  print  class.shov(vtab.get.vehicle(1054),  "driver") 
driver 


State:  1  (Idle) 

Leader:  52 

0 

(dbx)  print  cla8S.8hov(vtab.get.vehicle(1054) .  "driver  entity") 
driver 


State:  1  (Idle) 
Leader:  52 


entity 


Vehicle  ID:  54 
Location:  <  0.0  0.0  0.0  > 

•  •  • 

0 

(dbx)  print  cla88.8ho«(vtab.get.vehicle(1054) ,  "all") 
...prints  all  safobj  information... 
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Finally,  libclass  also  provides  run  time  debugging  support.  Rather  than  putting  conditionally 
compiled  printf’s  into  a  library,  an  author  should  use  the  macro  CLASSJDEBUG,  as  follows: 

idefine  DRIVER_DEBUG(vehicl«.id.  foxnat)  \ 

CLASS_DEBUG(vtab_get_vehicle(vehicle_id) .  drivar_us«r_data_handle .  \ 
format) ; 

void  driver_do_8om«thing(vehicle_id,  ...) 
int32  vehicle. id; 


DRIVER. DEBUG ( vehicle. id . 

("Vehicle  Xd:  Driver  doing  sooMthingXn" ,  vehicle.id)) ; 

> 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libclass,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  class_declare.jclass 

CLASS.PTR  class.declare.claasO 

class.declare.claas  declares  an  object  class.  Each  object  class  can  have  an  arbitrary  number 
of  slots  for  pointers  to  sub-class  data.  Tlio  class  handle  returned  by  this  function  is  referred  to  by 
each  sub-class  when  reserving  a  spot  for  its  data. 


3.2  class.j'eserve.user^ata 

int32  claas.reserve.user.dataCparent.clasB,  name,  printer) 

CLASS.PTR  parent.claas ; 

char  *naaa ; 

CUSS.PRIHTER  printer; 

‘parent.claas’ 

Identifies  the  class. 

‘name’  An  ASCII  string  naming  the  sub-class. 

‘printer’  Specifies  a  function  which  can  print  the  user  data.  This  function  should  take  one 
argument,  namely  the  user  data. 

class.reserve.uaer.data  not«^  a  p<itontial  sub-class  of  the  parent.claas  (some  instances 
of  the  parent  class  may  not  havo  tins  ,i.<.  a  sub-class).  The  parent.claas  was  declared  with 
claaa.declare.class  (see  Socti.ui  t  i  l.i.ss'dcclare'class],  page  9).  Note  that  name  and  printer 
are  used  only  for  debugging  pur; . . 


It  is  safe,  although  short-siulit*'*!.  t<>  p.L->  o  for  the  printer. 
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3.3  class^lloc_user.data 

CLASS_USER.DATA.TYPE  class.alloc.user.dataCclasa) 

CLASS.PTR  class: 

’class’  Identifies  the  class. 

class.alloc.user.data  allocates  a  block  of  memory  which  will  hold  pointers  to  the  various 
sub-class  data  structures  of  the  passed  class.  Store  the  return  value  of  this  as  the  ussr.data  of  the 
libpo  entry,  libvtab  vehicle,  Xt  widget,  or  whatever.  The  passed  class  is  the  id  of  the  class  declared 
with  class.dsclars.class  (see  Section  3.1  [class'declare'class],  page  9). 


3.4  class.free-user^ata 


void  class.fraa.uaar.dataCuser.data) 
CLASS.USER.DATA_TYPE  user.data; 


‘usar.data’ 

Identifies  the  user  data  to  be  freed. 


clas8_fr««_u8er_data  frees  the  block  of  memory  created  with  class.alloc.user.data,  as 
well  as  private  data  structures  (like  the  debugging  flags). 


Never  reference  passed  the  user.data  again  after  calling  this  function. 


3.5  class.set_user.jdata 


void  class.set.user.dataCparent.user.data,  handle,  user.data) 
CLASS.USER.DATA.TYPE  parent.user.data; 
int32  handle; 

CLASS.USER_DATA_TYPE  user.data; 


‘parent.user.data’ 

Pointer  to  a  block  of  libclass  user  data. 

‘handle’  Specifies  which  sub-class  user  data  slot  to  use. 
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‘user.data’ 

Specifies  the  user  data  to  be  stored  in  that  slot. 

class.set.user.data  sets  the  slot  for  a  particular  subclass  of  the  passed  user  data  memory 
block.  The  parent_\iser_data  is  a  block  created  with  class. alloc.user.data 
(see  Section  3.3  [class'alloc'user'data],  page  10),  and  the  handle  is  the  one  created  for  this  subclass 
with  clruis.reserve.user.data  (see  Section  3.2  [class'reserve'user'data],  page  9). 


3.6  class_get_user_idata 

CLASS_USER_OATA_TYPE  class.get.user.datafparant.user.data,  handle) 
CLASS_USER_DATA_TYPE  parent.user.data; 
int32  handle: 

‘parent.tuer.data’ 

Pointer  to  a  block  of  libclass  user  data. 

‘handle’  Specifies  which  sub-class  user  data  slot  to  get. 

class.get.user.data  gets  the  data  stored  in  a  particular  slot  of  the  passed  block  of  user.data 
memory.  The  parent.user.data  is  a  block  created  with  class.alloc.user.data  (see  Section  3.3 
[class'alloc'user'data],  page  10),  and  the  handle  is  the  one  created  for  this  subclass  with  class.resezre.user. 
(see  Section  3.2  [class'reserve'user'data],  page  9).  If  no  user  data  was  stored  in  this  slot  with 
class.set.user.data  (see  Section  3.5  [class'set'user'data],  page  10),  a  HULL  pointer  will  be  re¬ 
turned. 


3.7  class j3et...globaludata 


void  class.sat.global.dataCparent.usar.data,  user.data) 
CLASS .USER.DATA. TYPE  parent.user.data; 
CLASS.USER.DATA.TYPE  user.data; 


‘parent.user.data’ 

Pointer  to  a  block  of  libclass  user  data. 


‘iiser.data’ 


Specifies  the  user  data  to  be  stored  in  the  global  slot. 
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class .aet.global.data  sets  the  global  slot  of  the  passed  user  data  memory  block.  This  is 
analogous  to  class.set.user.data,  except  that  only  one  global  slot  is  provided. 


3.8  class_get_global_data 

CLASS_USER«DATA_TYPE  claas_get_global.data(parent_user_data) 
CLASS_USER_DATA_TYPE  parent.user.data; 

‘parent.user.data’ 

Pointer  to  a  block  of  Ubclass  user  data. 


class.get.global.data  gets  the  global  slot  of  the  passed  user  data  memory  block.  This  is 
analogous  to  class.get.user.data,  except  that  only  one  global  slot  is  provided. 


3.9  class^how 

void  class. shovCuser.data,  fields) 

CLASS.USER.OATA_TYPE  user.data; 
char  efields; 

‘user.data’ 

Pointer  to  a  block  of  libclass  user  data. 

‘fields’  Selects  which  fields  to  show. 

class. show  is  a  debug^ng  print  routine.  It  prints  the  named  fields  within  the  body  of  data 
pointed  to  by  user.data.  Multiple  fields  can  be  given,  separated  by  a  space,  comma,  or  other 
delimiter.  Also,  one  of  the  following  may  be  given  as  the  only  field: 

shat  Shows  names  of  slots  which  have  non-NULL  values, 
all  Shows  all  fields. 

This  function  can  be  called  from  ‘dbx’  to  examine  variables,  as  shown  in  the  example  (see 
Chapter  2  [Examples],  page  3). 
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3.10  CLASS-DEBUG 


void  CLASS.DEBUG (user. data,  handle,  (fonnat.string.  arg.  args...)) 
CLASS_USER.DATA.TYPE  user.data; 
int32  handle; 


‘user.data’ 

Pointer  to  a  block  of  libclass  user  data. 

‘handle’  Specifies  which  sub-class  user  data  slot  to  test. 

CLASS.DEBUG  is  a  macro  which  calls  printf  with  the  passed  format/args  on  if  the  debugging 
is  on  for  that  slot  on  that  class  in  this  block.  Will  also  print  if  debugging  is  on  for  that  slot/class 
globally.  See  the  example  (see  Chapter  2  [Examples],  page  3)  for  example  usage. 


3.11  class.get.debug 


int32  class.get.debugCuser.data,  handle) 
CLASS.USER.DATA.TYPE  user.data; 
int32  handle; 


‘user.data’ 

Pointer  to  a  block  of  libclass  user  data, 
‘handle’  Specifies  which  sub-class  user  data  slot  to  test. 


class.get.debug  determines  if  debugging  output  is  appropriate  for  the  particular  handle  of 
the  particular  instance  (or  if  it  is  set  globally).  Returns  1  if  debugging  is  on,  0  if  off.  CLASS_DEBUG 
is  implemented  using  this  function.  An  application  may  call  this  when  enabling  debugging  triggers 
more  than  just  a  printf  (such  as  turning  on  extra  error  checks). 


3.12  class-idebug-byname 


void  class_debug_bynaffle(user_data.  fields,  bit) 
CLASS.USER.DATA.TYPE  user.data; 
char  efields; 

int32  bit ; 
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‘user.data’ 

Pointer  to  a  block  of  libclass  user  data. 

‘fields’  Selects  which  fields  to  enable/disable  debug^ng. 

‘bit’  1  enables  debugging;  0  disables. 

clas8_dabug_bynane  sets  debugging  flags  associated  with  classes  listed  in  fields  either  on  (bit 
==  1),  or  off  (bit  ==  0).  If  a  parent.user.data  is  passed,  debugging  is  set  for  that  object  only. 
If  a  NULL  pointer  is  passed  as  the  parent.user.data,  debugging  is  set  globally.  The  special  value 
all  can  be  passed  as  the  field,  to  set  all  debugging  field  for  the  object. 

Note  that  the  sequence  class.debug.  byname  (NULL,  ''all",  1)  enables  all  debugging  for  all 
objects. 


3.13  class_showjnames 
void  class.shov.namesO 


claas_8ho«.nane8  prints  the  named  fields  within  the  slots  of  aU  valid  classes. 
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1  O  vervie w 


Libcmdline  provides  a  flexible  command  line  processor  with  the  following  features: 

•  Command  line  arguments  are  specifled  succinctly  in  the  code,  in  a  way  which  makes  it  easy  to 
add  new  ones. 

•  Each  argument  has  accompanying  information  so  libcmdline  can  print  help,  summarize  selected 
values,  and  do  error  checking. 

•  Each  user  can  modify  the  default  options  used  with  each  application  program  via  an  envi¬ 
ronment  variable.  The  name  of  this  variable  is  derived  from  the  name  of  the  executable  by 
capitalizing  it  and  appending  ARCS.  Hence,  default  arguments  to  an  executable  named  phan¬ 
tom  could  be  stored  in  the  environment  variable  PHANTOMARGS.  This  allows  the  creation 
of  one  executable  which  can  use  symbolic  links  to  yield  different  names  and  default  behavior 
(safstation,  safsim,  logger,  etc.). 

•  Hence,  arguments  can  be  specifled  in  three  places:  in  the  code,  in  an  environment  variable, 
and  on  the  command  line  (in  increasing  order  of  precedence). 

•  Each  command  line  argument  can  be  a  switch,  the  mere  presence  of  which  indicates  a  value, 
or  it  can  be  followed  by  one  or  more  values  (integers,  floating  point  numbers,  strings,  or  any 
combination). 

•  Arguments  can  be  interdependent,  so  for  example,  the  user  may  only  be  allowed  to  specify  an 
exercise  ID  if  running  with  the  network;  or  specify  a  starting  X  if  a  starting  Y  is  also  specified 
(and  vice-versa). 

•  Multiple  dependencies  can  be  either  conjunctively  or  disjunctively  combined,  so  for  example, 
the  interdependent  X  and  Y  can  also  be  dependent  upon  a  Z  and  upon  there  not  being  a 
starting  grid  specifled,  and  the  Z  can  be  dependent  upon  there  being  an  X  or  a  starting  grid 
specifled. 

•  Unrecognized  arguments  are  given  back  to  the  caller,  so  they  can  be  passed  to  other  command 
line  processors  (such  as  Xtlnitialize).  These  unrecognized  arguments  can  be  given  either  on 
the  command  line  or  in  the  user  environment  variable  (so  for  example,  STATIONARGS  can 
be  "-g  800x500",  which  might  not  be  recognized  by  libcmdline,  but  instead  would  be  passed 
on  to  Xt). 

•  Arguments  can  be  abbreviated  by  ending  them  with  a  For  example,  if  the  application 
expects  -exercise  1,  the  user  can  type  -e.  1  to  achieve  the  same  result.  The  reason  for  the 
explicit  is  that  some  arguments  are  not  intended  to  be  recognized  (such  as  the  -g  option 
just  described). 

The  interface  to  libcmdline  is  through  an  array  of  CMD.OPTION  structures,  although  an  applica¬ 
tion  wiU  generally  instead  use  a  structure  of  various  parallel  structures,  and  speci^  values  with 
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aggregate  initialization  (see  Chapter  2  [Examples],  page  3). 
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2  Examples 


The  following  code  segment  gives  examples  of  all  libcmdline  features.  This  code  serves  as 
a  hypothetical  example;  it  does  not  represent  actual  ModSAF  code.  See  Chapter  4  [Options 
Structures],  page  13,  for  more  information. 


•include  "libcsidline.h'' 

•include  <8tdezt.h>  /econuBon/ include/global*/ 

struct 

{ 

CMD.TOGGLE.QPTION  safsia; 

CMD.T0GGLE_0PTI0N  saf station; 

CMO_STRING.OPTION  terrain; 

CMD.T0GGLE_0PTI0N  network; 

CMD.INTEGEILOPTION  exercise; 

CMD.B00LEAN.0PTI0N  synch; 

CMD.IirrEGER.OPTION  ncache; 

CMD.STRING.OPTION  startmap; 

CHD.ZNTEGEILOPTION  scalenua; 

CMD.INTEGEILQPnON  scaledenom; 

CMD.FL0AT.0PTI0H  mdseed; 

CMD.IHTEGEILQPTIOM  xloc; 

CMD.INTEGEILOPTIOM  yloc; 

}  options  ■  { 

i 

"SAFSIN"  ,  “Selects  whether  to  run  SAF  sinulation  processes"  . 

HULL  , 

CND. TOGGLE  ,  “sia"  .  "nosia"  ,  TRUE  , 

>  . 

{ 

“SAFSTATIOH"  ,  "Selects  whether  to  run  SAF  workstation  processes"  , 
HULL  , 

CMO. TOGGLE  ,  "station"  ,  "nostation"  ,  TRUE  , 

}  , 

•C 

"Terrain  Database  Haae"  ,  "Specifies  terrain  database"  , 
"stationisia"  , 

CMD.STRIHG  ,  "terrain"  ,  "nowhere"  ,  "knox-0311"  , 

>  , 

"Hetwork"  ,  "Selects  whether  to  use  network"  , 

HULL  , 

CMD.TOGGLE  ,  "network"  ,  "nonet"  ,  TRUE  , 

>  . 

"Exercise  ID"  ,  "Specifies  simulation  exercise  id"  , 

"network"  , 
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CMD.IMTEGER  ,  "•xercise”  .  HULL  .  1  , 

>  . 

■c 

"Synchronous"  ,  "Run  X  windows  in  synchronous  mode  for  debugging"  , 
"station"  , 

CMD.BOOLEAM  ,  "synch"  .  "asynch"  .  FALSE  , 

}  . 

•C 

"Hap  Cache"  ,  "Specifies  number  of  map  screens  to  cache"  , 

"station"  , 

CMD.IHTEGER  ,  "mcache"  .  "nomcache"  ,  2  , 

>  . 

"Hap  Starting  Grid"  .  "Specifies  initial  location  of  map"  . 
"station"  , 

CHD.STRING  ,  "starimap"  ,  "center"  ,  NULL  , 

}  , 

"Hap  Starting  Scale"  ,  "Specifies  initial  map  scale  •  :  , 

"station"  , 

CHD.INTEGER  .  "scale"  .  NULL  .  1  . 

}  . 

/*  Nap  Starting  Scale  takes  two  arguments  «/ 

NULL  ,  NULL  ,  NULL  ,  CHD.INTEGER  ,  HULL  ,  HULL  ,  200000  , 

>  . 

{ 

"Random  Number  Seed"  ,  "Seed  value  for  random  nusiber  generator"  , 
"Sim"  , 

CHD.FL0AT  ,  "rand"  ,  HULL  ,  0.0  , 

>  . 

"X"  ,  "Starting  X  location"  , 

"yftstation"  , 

CHD.INTEGER  ,  "x"  ,  NULL  ,  0*  , 

}  . 

"Y"  ,  "Starting  Y  location"  , 

"ztstation"  , 

CHD.IMTEGER  ,  "y"  .  HULL  ,  0  , 

}  . 


mainCargc,  argv) 
int  argc ; 
char  *argvC] ; 

int32  leftover. argc : 
char  ♦♦leftover.argv; 
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cod.proceas.optionsCargc,  argv.  /*  args  to  mainO  */ 

tleftover.argc,  ftleftover.argv.  /♦  imrecognized  */ 
(CMD.OPTIOH  *)toptions,  /*  options  array  •/ 
sizeof (options) ,  /*  size  of  options  array 
TRUE  /•  Verbose  mode  •/ 

); 


/*  Pass  remaining  args  to  X  windoss  */ 
XtInitialize(XtInitialize(argvCOj .  "Saf",  NULL,  0. 

tleftover.argc,  lef tover.argv) ; 

cmd_gripe(leftover_argc,  leftover.argv) ; 

/*  Example  usage ...  */ 

printf ("Reading  /saf/terrain/XsXn”.  options. terrain. value) ; 


It  is  also  possible  to  describe  command  line  options  in  multiple  arrays  by  aggeregating  them  and 
then  processing  the  resulting  structure.  This  is  useful  for  keeping  command  line  options  associated 
with  modules.  For  example,  one  module  could  may  control  the  application  processes: 


finclude  "libcmdline.h" 

finclude  <8tdezt.li>  /ecommon/include/global*/ 

struct 

{ 

CMD.T0GGLE_0PTI0N  safsim; 

CMD.T0GGLE.0PTI0R  safstation; 

}  process.options  ■  { 

i 

"SAFSIM"  ,  "Selects  whether  to  nm  SAF  simulation  processes"  , 

NULL  . 

CMD.TOGGLE  .  "sim"  .  "nosim"  ,  TRUE  , 

>  , 

"SAFSTATION"  ,  "Selects  whether  to  run  SAF  workstation  processes"  , 
NULL  . 

CMD.TOGGLE  ,  "station"  ,  "nostation"  .  TRUE  , 

}  . 


void  process.init  (options,  sizeof .options ,  map) 
CMD.OPTION  eeoptions; 
uint32  *sizeof .options ; 

CMD.TYPES  ***map; 

CDd.aggregate  (options,  sizeof .opt ions, 

(CMD.OPTION  *)Aprocess.options, 
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sizeof  (process.options) , 
map) ; 

} 

void  process.simul  () 

{ 

printf  ("Simulation  process  is  %s\n". 

process.options .safsim. value  ?  "On"  :  "Off"); 
printf  ("Workstation  process  is  XsVn". 

process.options. saf station. value  ?  "On"  :  "Off"); 

} 


Another  module  may  control  the  network: 


•include  "libcmdline.h" 

•include  <stdezt.h>  /ecommon/include/globad*/ 
struct 

CMD.TaGGLE_OPTION  netsork; 

CMD.INTEGEILOPTION  exercise; 

}  netvork.options  ■  { 

< 

"Network"  ,  "Selects  whether  to  use  network"  , 

NULL  , 

CMD.TOGGLE  ,  "network"  ,  "nonet"  ,  TRUE  , 

}  , 

"Exercise  ID"  ,  "Specifies  sianilation  exercise  id"  , 
"network"  , 

CND.INTEGER  ,  "exercise"  ,  NULL  ,  1  . 

>  , 


void  network_init  (options,  sizeof .opt ions,  map) 
CMD.OPTION  eeoptions; 
uint32  esizeof .options ; 

CMD.TYPES  ***map; 

< 

caid_aggregate  (options,  sizeof. options, 

(CMD.OPTION  e)tnetwork_ options, 
sizeof  (network.options) , 
map); 

> 

void  network.8imul  0 

i 


printf  ("Network  is  Xs\n", 
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neteork_option8. network. value  ?  "On"  :  "Off"); 
if  (netvork_options .network. value) 
printf  ("Exercise  ID  is  Xd\n",  netsork_options. exercise. value) ; 

} 

The  options  from  these  two  modules  may  be  combined  as  follows: 
iinclude  "libcmdline.h" 

tinclude  <8tdext.h>  /ocoomion/include/globale/ 

extern  void  process.init  (); 
extern  void  process.simul  (); 
extern  void  network_init  (); 
extern  void  network_8imul  (); 

mainCargc.  argv) 
int  argc ; 
char  *argvC] ; 

{ 

int32  lef tover.argc : 
char  •♦leftover. argv; 

CMD.OPTIOH  ♦options; 
uint32  sizeof .options; 

CMD.TYPES 

sizeof. options  >  0; 

process.init  (koptions,  ksizeof. options,  tmap); 
network.init  (toptions,  tsizeof. options,  tmap); 

cmd.process.aggregate.opt ions (argc,  argv,  /♦  args  to  mainO  ♦/ 

tleftover.argc,  tleftover.argv,  /♦  unrecognized  ♦/ 
options,  /♦  options  array  ♦/ 
sizeof. opt ions,  /♦  size  of  options  array  ♦/ 
map,  /♦  option  value  map  ♦/ 

TRUE  /♦  Verbose  mode  ♦/ 

); 

process.simul  (); 
network.simul  () ; 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libcmdline,  including  the  format  and 
meaning  of  its  arguments,  and  the  moaning  of  its  return  values  (if  any). 


3.1  cmd^rocess_x>ptions 


void  CBd_proc«88_optiona(argc.  argv,  leftover.argc,  leftover.argv, 

optiona,  aizeof.optiona,  verboae) 

int  argc ; 

char  *argvC]; 

int32  *leftovar.argc: 

char  **leftover.argvC] ; 

CMD_0PTI0N  *option8: 
uint32  sizeof. options : 

int32  verbosa ; 


‘argc,  argv’ 

Arguments  to  main 
‘leftover.argc,  leftover.argv’ 

Returns  unmatched  arguments  for  processing  by  other  command  line  parsers  (such  as 
Xtlnitialize) 

‘options’  Specifies  array  of  known  options,  returns  values  of  those  options 
‘sizaof.options’ 

Specifies  the  size  of  the  options  array  (in  bytes) 

‘verbose’  Specifies  whether  to  print  values  of  options 

cffld_proces8_options  processes  command  line  options,  providing  a  value  for  each  (either  a 
system  default,  an  environment  default,  or  a  command  line  switch  value).  The  options  which  are 
not  recognized  are  passed  back  in  leftover_argc/v. 


3.2  cm d -aggregate 


int32  cmd.aggregate(aggregate,  sizeof .aggregate,  piece,  sizeof .piece,  map) 
CND.OPTION  **aggregate: 
uint32  *sizeof .aggregate; 

CMD.OPTIOH  epiece; 
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uint32  sizeof. piece; 

CMD.TYPES  ***map; 

‘aggregate’ 

Pointer  to  a  variable  containing  a  pointer  to  the  aggregate  options  array.  The  iisor 
simply  needs  to  declare  the  variable,  cmd. aggregate  will  fill  it  in  properly. 

‘sizeof .aggregate’ 

A  pointer  to  a  variable  containing  the  size  of  the  aggregate  options  array.  The  usfr 
should  set  the  value  of  the  variable  to  zero  (0)  before  the  first  call  to  cmd. aggregate, 
‘piece’  An  options  array  to  be  added  to  the  aggregate  array. 

‘sizeof .piece’ 

The  size  of  piece. 

‘map’  A  pointer  to  a  variable  containing  a  pointer  to  a  map  array.  The  user  simply  needs  to 

declare  the  variable,  cmd. aggregate  will  fill  it  in  properly. 

cmd.aggregate  adds  a  command  line  options  array  (piece)  to  a  dynamically  allocated  command 
line  options  array  (aggregate). 


3.3  cmd.process jaggregate_options 


void  cmd_proce88.aggregate_option8(argc,  argv,  lef tover.argc , 

leftover. argv,  optione, 
sizeof. options,  map,  verbose) 

int  argc ; 

char  •argvD; 

int32  eleftover.argc; 

char  •♦leftover.argvG ; 

CMD.OPTION  *options; 
uint32  sizeof. options; 

CMD.TYPES  ♦♦map; 
int32  verbose ; 


‘argc,  argv’ 

Arguments  to  main. 

‘leftover.argc,  leftover. argv’ 

Returns  unmatched  arguments  for  processing  by  other  command  line  parsers  (such  as 
Xtinitialize). 

‘options’  Specifies  aggregated  array  of  known  options.  Constructed  in  calls  to  cmd.aggregate. 
‘sizeof .opt ions’ 

Specifies  the  size  of  the  options  array  (in  bytes).  Determined  in  calls  to  cmd.aggregate. 
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‘map’  Contains  a  mapping  the  aggregate  options  array  and  each  of  the  pieces. 

‘verbose’  Specifies  whether  to  print  values  of  options 

cmd.process.aggregate.options  processes  command  line  options  contained  and  an  aggregate 
options  array.  The  value  for  each  option  (cither  a  system  default,  an  environment  default,  or  a 
command  line  switch  value)  is  copied  into  the  option  arrays  that  make  up  the  aggregate  array.  The 
options  which  are  not  recognized  are  passed  back  in  leftover_argc/v. 


3.4  cmd_gripe 

void  cmd_gripe(leftover_argc,  leftover.argv) 
int32  leftovar.argc; 
char  •leftover.argv  □ ; 

‘leftovar.argc’ 

Specifies  the  number  of  unrecognized  options 
‘leftover.argv’ 

Specifies  list  of  unrecognized  options 
cmd_gripe  print  a  message  listing  unrecognized  arguments. 
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4  Options  Structures 


Libcmdllne  uses  six  structures  to  represent  command  line  options.  The  first  (CMD_0PTI0N)  is  a 
generic  structure  in  which  default  values  are  specified  and  resulting  values  are  returned  using  the 
following  union: 


union  cmd.types 

int32  boolean: 
int32  toggle; 
int32  Integer; 
char  *string; 
float32  floating: 

}; 


The  remaining  five  structures  are  identical  to  this  master  structure,  except  that  rather  than 
using  a  union,  the  default  and  resulting  value  fields  are  of  a  single  simple  type.  This  allows  these 
values  to  be  specified  using  aggregate  initializers  in  C,  for  example: 


CMD.T0GGLE_0PTI0N  safsim  « 

"SAFSIM"  ,  "Selects  whether  to  run  SAF  simulation  processes"  , 
NULL  . 

CMD.TOGGLE  ,  "sim"  ,  "nosim"  ,  TRUE  , 

}; 


This  type  of  initialization  is  not  possible  in  C  when  the  structure  contains  unions. 


The  CHD.OPTION  structure  is  defined  as  follows: 


typedef  struct  cmd.option 

/*  Descriptive  name  of  thing  controlled  with  option  */ 
char  *name ; 

/*  Description  of  purpose  of  this  option  •/ 
char  *help: 

/*  If  non-NULL,  specifies  an  option  which  must  be  selected  (if  the 

*  name  is  that  of  an  option,  the  value  associated  with  that  option 

*  must  be  non-zero;  if  the  name  is  that  of  an  anti.option,  the 

*  value  must  be  zero)  for  this  option  to  be  allowed. 

*/ 
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char  *depandant_option; 

/*  CMD.BOOLEAN,  CMD.FLOAT,  etc.  */ 
int32  type ; 

/*  Command  line  option  (preceded  with  -  on  command  line)  */ 
char  *option; 

/*  Version  of  the  option  which  indicates  0.  May  specify  NULL  to 

*  indicate  no  such  option  when  type  INTEGER,  STRING,  or  FLOAT; 

*  must  give  a  value  when  type  BOOLEAN  or  TOGGLE. 

*/ 

char  *anti_option: 

/*  Default  value  (Note  the  mis-spelling  because  default  is  reserved)  */ 
union  cmd.types  default; 

/*  Resulting  value  (don’t  bother  to  initialize)  */ 

\mion  cmd.types  value; 

}  CMD.OPTION; 


Each  held  is  described  in  the  following  sections. 


4.1  name 

The  name  of  the  option  is  used  for  twt>  purposes: 

•  When  processing  the  command  line  with  the  Verbose  flag  set  to  TRUE,  the  name  is  used  in 
printing  the  value. 

•  If  the  name  is  not  specified  (NULL),  the  option  is  treated  as  a  continuation  of  the  previous 
option.  In  this  way,  a  single  option  r.-in  take  more  than  one  value. 


4.2  help 

The  help  string  specified  for  •  ••  li  is  a  description  of  what  the  option  controls.  Help 

is  used  when  one  of  the  flags  Ip.  -h.  or  -?.  Help  strings  should  kept  short  to  avoid 

wrapping  at  the  end  of  the  srr<'<'ti 


Chapter  4:  Options  Structures 


15 


4.3  dependent_option 

depeadentjoption(s)  are  those  which  must  be  specified  along  with  the  current  option.  More  than 
one  option  can  be  listed  here,  tied  together  with  the  others  using  the  characters  ‘ft’  or  ‘I’,  meaning, 
respectively,  that  all  or  at  least  one  of  the  dependent  options  must  be  given.  (Don’t  use  any  spacf*s 
in  this  string.) 

Refering  to  a  boolean  or  toggle  option  in  the  list  of  dependencies  indicates  that  the  value  of 
that  option  must  be  TRUE.  Referring  to  any  other  kind  of  option  indicates  that  the  value  of  that 
option  must  be  different  than  the  default  value.  Finally,  referring  to  an  anti-option,  indicates  that 
that  option  must  have  a  zero  (or  NULL)  value.  Note  that  depending  on  an  option  with  more  than 
one  value  (see  Section  4.1  [name],  page  14),  will  perform  these  tests  on  the  first  value,  but  not  on 
any  continuations. 

Dependencies  are  not  checked  until  after  all  command  line  arguments  have  been  processed,  so 
options  may  be  interdependent  (-a  depends  on  -b,  and  -b  depends  on  -a). 


4.4  type 

The  type  of  an  option  determines  how  its  value  is  determined,  printed,  and  stored.  The  following 
types  are  defined: 

CND.B00LEAH 

A  True  (1)  or  False  (0)  value.  Simply  listing  the  option  on  the  command  line  is  sufficient 
to  specify  a  True  value.  Similarly,  listing  the  anti-option  specifies  a  False  value. 

CMD.TOGGLE 

An  On  (1)  or  Off  (0)  value.  The  only  difference  between  TOGGLE  and  BOOLEAH  is  in  the 
way  the  value  is  printed. 

CND.INTEGER 

An  integer  value. 

CHD.STRIHG 

A  character  string. 

CMD_FL0AT 

A  floating  point  number  (in  a  format  recognized  by  scanfO)). 

For  each  type,  there  is  a  variant  of  the  CND.OPTIOII  structure.  They  are  as  follows: 
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CMD_B00LEAN 

CMDJOOLEAN.OPTION 

CMD.TOGGLE 

CMD-TOGGLE-OPTION 

CMD.IKTEGER 

CMDJNTEGER.OPTION 

CMD.STRING 

CMD^TRING.OPTION 

CMD.FLOAT 

CMD_FLOAT.OPTION 


4.5  option 

The  option  string  is  the  sequence  of  characters  which  are  specified  on  the  command  line  with 
a  to  select  this  option.  This  should  be  NULL  when  the  option  is  a  continuation  of  a  previous 
option  (see  Section  4.1  [name],  page  14). 


4.6  anti_option 

The  antijoption  string  is  a  sequence  of  characters  which  can  be  specified  on  the  command  line 
with  a  to  indicate  a  0  or  NULL  value.  Note  that  selecting  the  anti-option  nullifies  all  continuations 
of  the  option  as  well. 


For  boolean  and  toggle  options,  it  is  mandatory  to  specify  an  anti-option  (otherwise  environ¬ 
mental  defaults  could  not  be  overridden  on  the  command  line).  For  other  types  of  options,  NULL 
may  be  specified  to  indicate  its  absence. 


4.7  default 

The  default  value  (misspelled  default  because  of  conflicts  with  the  C  language)  is  the  value 
which  is  used  unless  overridden  by  the  evironment  variable  or  on  the  command  line. 
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4.8  value 

The  value  ultimately  selected  for  each  option  is  placed  here.  This  is  a  write-only  field  in  libcmd- 
line,  any  initial  value  will  be  overwritten  by  cmd.process.optionsC). 
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1  O  vervie w 


Libcollision  provides  a  3D  physical  model  of  collision  detection.  It  can  detect  collisions  with 
other  network  entities  (platforms,  missiles,  and  structures),  as  well  as  treelines,  buildings,  and  tho 
ground.  This  library  is  also  responsible  for  generating  and  processing  collision  PDUs.  The  library 
uses  a  parametrically  controlled  timing  heuristic  to  filter  out  redundant  collisions  (such  as  when 
both  parties  in  the  collision  send  one  another  collision  PDUs). 

This  library  handles  both  the  simple  detection  of  intersections  with  nearby  features  used  for  slow- 
moving  ground  vehicles,  as  well  as  the  more  complex  detection  of  collisions  needed  by  a  fast  moving 
vehicle  which  may  jump  a  considerable  distance  between  ticks.  For  example,  a  missile  traveling  at 
Mach  1,  ticking  at  2  Hz  will  jump  about  165  meters  each  tick.  Hence,  a  ray  must  be  run  from  the 
old  position  to  the  new  position  to  determine  if  any  features  were  intersected  along  the  way. 

The  parameters  used  by  a  vehicle  (or  missile)  for  collision  detection  are  specified  in  its  configu¬ 
ration  file  as  follows: 


(SM_Colli8ion  (check  {tr««8>  <building8>  {ground} 

{platforms}  {missiles}) 
(announce  {trees}  {buildings}  {ground} 
{platforms}  {missiles}) 
(duration  <  integer  iiiilliseconds>) 
(feature_ma88  <real  kg>) 

(fidelity  [highllov]) 


The  first  parameter,  check,  lists  those  things  for  which  collision  detection  is  required.  This 
affects  performance  in  two  ways: 


•  Each  tick,  libcollision  checks  for  collisions  with  those  things  listed.  Each  additional  item  has 
some  added  cost. 

•  When  a  collision  PDU  is  received,  the  collision  is  only  reported  to  the  parent  object  (see 
Section  2.2  [coll'class'init],  page  3)  if  the  colliding  entity  matches  one  of  the  types  listed.  For 
example,  if  a  tank  is  configured  to  not  check  for  collisions  with  buildings,  then  a  collision 
emminating  from  a  network  entity  of  domain  Structure  will  not  be  passed  on. 

The  annoimce  parameter  lists  those  collision  which  should  be  announced  on  the  network  (via  a 
collision  PDU)  when  a  collision  is  detected  locally.  For  example,  a  missile  would  list  platforms  in 
its  check  list,  but  not  in  its  atimounce  list,  since  the  missile  will  be  sending  an  impact  PDU  instead 
of  a  collision  PDU. 
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The  duration  value  is  used  in  a  simple  heuristic  which  avoids  redundant  collision  detection. 
When  a  collision  is  detected,  the  time  of  that  collision  is  noted.  Each  similar  collision  (with  the  same 
entity  or  terrain  feature)  which  occurs  within  the  specified  duration  after  the  ori^nal  collision  is 
then  ignored.  This  gives  the  dynamics  software  a  chance  to  back  the  vehicle  out  of  the  collision, 
and  protects  from  redundant  damage  assessment  when  both  parties  in  a  collision  detect  it  and  issue 
collision  PDUs. 

The  feature.mass  parameter  specifies  the  mass  which  will  be  passed  up  to  the  parent  object 
when  the  software  detects  a  collision  with  a  terrain  feature.  This  is  intended  to  simplify  encoding 
of  damage  models. 

Finally,  the  fidelity  parameter  (which  has  a  value  of  high  or  low)  is  used  to  determine  the 
accuracy  (and  hence  computational  expense)  of  the  algorithms  used  in  collision  detection.  The 
differences  are  primarily  with  respect  to  the  point  of  intersection. 

In  the  high  fidelity  model,  the  point  of  intersection  will  be  accurately  determined,  using  the 
parallelepipeds  described  in  libphysdb  (width,  length,  height).  For  example,  a  collision  with  a 
building  will  be  detected  exactly  as  the  front  edge  of  the  vehicle  touches  the  building. 

In  contrast,  the  low  fidelity  model  detects  collisions  with  terrain  features  using  a  bounding  cube 
which  is  aligned  with  the  compass  axes,  and  is  as  lai^e  as  the  vehicle’s  largest  dimension.  Collisions 
with  other  vehicles  are  detected  using  a  simple  spherical  model  of  vehicles. 

Note  that  the  low  fidelity  model  does  run  the  ray  intersection  test  described  above,  so  it  may 
be  used  for  crude  missile  simulations. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libcoUision,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  colljnit 

void  coll.init (packet. valve,  event.id,  exercise.id,  sinuaddr,  protocol) 
PV.VALVE.PTR  packet. valve; 

int32  *event.id; 

uintS  exercise.id; 

SiaulationAddress  *8in.addr; 
int32  protocol ; 

‘packet.valve’ 

Specifies  the  packet  valve  used  to  send/receive  collision  PDUs 

‘event.id’ 

Specifies  a  pointer  to  a  static  host  event  counter 
‘exercise.id’ 

Specifies  the  exercise  on  which  to  broadcast  collision  PDUs 

‘siouaddr’ 

Specifies  simulation  address  for  outgoing  event  DIS  IDs 

‘protocol’ 

Specifies  protocol  in  use  (0  for  SIMNET,  DIS.PROTOCOL. VERSION.*  for  DIS) 

coll.init  initializes  libcoUision.  Call  this  before  calUng  2uiy  other  Ubcollision  functions.  The 
packet.valve  is  created  with  a  call  to  pv.create. valve. 


2.2  coll.class Jnit 

void  coll.class.init (parent. class,  callback) 
CLASS.PTR  parent.class ; 

C0LL.CALLBACK  callback; 

‘psurent.class’ 

Specifies  the  parent  class  (probably  safobjjclass) 
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‘callback’ 

Specifies  the  function  to  call  when  collisions  occur 

coll.clasa.init  creates  a  handle  (index)  for  attaching  collision  class  information  to  vehicles. 
The  parent.class  is  one  created  with  class.declara.class.  The  callback  function  should  be 
declared: 


void  callbackCvehicle.id.  position,  coll.type, 

other.id,  othar.mass.  other. velocity) 
int32  vehicle.id; 
float64  position [3] ; 
uint32  coll.type ; 
int32  other.id; 
float64  other.mass; 
float64  other. velocity [3] ; 


This  is  called  when  a  collision  occurs,  after  the  collision  is  announced  on  the  network  (provided 
the  type  of  collision  is  listed  in  the  announce  parameter  list).  The  position  sent  is  the  point  of 
collision.  The  coll_t3rpe  code  is  one  of  the  following: 


COLL.TIIEES 

Indicates  crossing  a  treeline  or  canopy  edge. 

COLL.BUILDINGS 

Indicates  crossing  a  building  or  other  structure.  If  the  other  structure  is  represented 
on  the  network,  the  vehicle  ID  of  that  structure  will  be  provided. 

C0LL.GR0UND 

Indicates  a  collision  with  the  ground. 

C0LL.PLATF0RMS 

Indicates  intersecting  a  platform  (vehicle,  DI,  etc.). 

COLL_NISSILES 

Indicates  intersecting  a  missile  (an  entity  on  the  network  with  a  munition  type). 

If  the  collided  entity  exists  in  the  vehicle  table,  its  ID  is  given  in  the  other.id  field.  For 
collisions  with  terrain  features,  the  other.mass  will  be  that  specified  in  the  feature.mass  field  of 
the  parametric  data,  and  the  other.velocity  will  be  zero. 


2.3  coll_create 


void  coll.create (vehicle.id,  parms) 
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int32  vehicle.id; 

COLLISION.PARAMETRIC.DATA  *panns: 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘panns’  Specifies  initial  parameters 


coll.create  creates  the  collision  cliL^s  information  for  a  vehicle  and  attaches  it  to  the  vehicle’s 
libclass  user  data. 


2.4  coll_destroy 

void  coll.destroy (vehicle. id) 
int32  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

coll.destroy  frees  the  collision  class  information  for  a  vehicle. 


2.5  coll^rocess^dus 

void  coll.process.pdus (vehicle.id) 
int32  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  II) 

coll.process.pdus  procps-**^  .«;i\  .  ••ilt«i«m  PDUs  received  and  enqueued  since  the  last  call  to 
this  function.  This  may  invok*-  •.lilli.trk  function  passed  to  coll.class.init  if  a  received 
collision  is  not  one  which  wa.'.  .<:r>  ••!  .  <!•  (•<<  t<-<i  locally.  This  should  be  called  early  in  a  vehicle’s 
tick,  preferably  before  updatinu  '•  *  lin  order  to  ensure  minimal  visual  latency),  and  before 

calling  coll.tick. 


6 


LibCollision  Programmer’s  Guide 


2.6  coil-tick 

void  coll_tick(vehicle_id,  ctdb) 
int32  vehicle. id; 

CTDB  ectdb; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘ctdb’  Specifies  the  terrain  database 

coll.tick  ticks  the  collision  sub-class.  During  the  tick,  if  a  collision  is  detected,  a  packet  may 
be  sent  and  the  callback  function  passed  to  coll.class.init  may  be  invoked. 


2.7  coll-get ^current 

void  coll_get.current(vehicle_id,  current) 
int32  vehicle. id; 

COLL. CURRENT  ^current; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘current’  Returns  current  collision  information 

coll.get.current  returns  a  read-only  list  of  vehicles  which  have  been  collided  with  recently. 
The  user  data  attached  to  each  vehicle  in  the  list  specifies  the  simulation  clock  value  at  the  time 
of  collision.  It  is  safe  to  iterate  over  the  list  of  vehicles,  provided  that  iteration  does  not  span  more 
than  one  tick  (i.e.,  the  collision  subclass  will  also  be  iterating  over  this  list).  This  function  also 
gives  information  about  the  most  recent  terrain  collision.  The  COLL.CURRENT  structure  is  defined 
as  follows: 


t3rped«f  struct  coll.current 

/*  A  list  of  recent  vehicle  collisions  */ 

VTAB.LIST  list; 

/*  A  description  of  the  most  recent  terrain  collision  */ 
struct 

i 

uint32  coll.type;  /*  COLL_TREES,  etc.  */ 
uint32  sioulation.clock; 
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float64  location [3] : 
float64  mass; 

>  moat.recent_terrain; 

}  COLL.CURRENT; 


2.8  collJgnore 


void  coll_ignore(vshicle.id,  opsration,  othsr.id) 
int32  vshicls.id; 

C0LL_IGN0RE.0P  opsration; 
int32  othsr.id; 


‘vshicls.id’ 

Specifies  the  vehicle  ID 

‘operation’ 

Specifies  whether  to  add  or  remove  the  other  vehicle  from  the  ignore  list 

‘other. id’ 

Specifies  vehicle  to  ignore 

coll.ignore  adds  or  removes  a  vehicle  to  the  list  of  vehicles  which  should  be  ignored  in  collision 
detection.  This  can  be  used,  for  example,  to  avoid  detecting  collisions  between  platforms  and  their 
missiles;  or  aircraft  and  carriers. 

operation  has  one  of  the  values: 

C0LL.ADD  Ignore  collisions  with  other.id. 

C0LL.REN0VE 

Do  not  ignore  collisions  with  other.id. 
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3  A  ccess  K  eys 


In  addition  to  the  functions  just  described,  libcollision  also  provides  libaccess  keys  with  which 
many  variables  can  be  fetched  at  once.  These  keys,  and  the  type  of  argument  they  expect  are  given 
below: 

colijcurrent 


C0LL_CUR11ENT  *arg 
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1  Overview 


Libcomponents  is  an  architectural  library  which  provides  a  level  of  abstraction  away  from  specific 
component  interfaces.  For  example,  although  a  vehicle  may  have  one  of  several  sensor  models,  the 
interfaces  to  these  models  are  all  basically  identical.  Libcomponents  allows  an  application  to  give 
commands  to  its  "sensor"  without  knowing  which  sensor  model  is  being  used.  Through  the  use 
of  libparmgr,  libcomponents  also  provides  a  facility  to  change,  add,  or  delete  a  component  model 
after  a  vehicle  has  already  been  created. 

The  layering  of  the  software  looks  something  like  this: 

- - - specific  layer - - - 

TrackedHull  FUAHull  BallisticGun 

VheeledHull  RWAHull  RocketLauncher  Radar 

DZHull  NissileHull  GenericTurret  HissileLauncher  Visual 

-  generic  layer  - 

Hull  Turret  Gun  Sensor 

-  architectural  layer  - - - - - 

Components 


The  software  layering  diagram  shown  above  has  been  currently  implemented  via  the  ModSAF 
library  structure  shown  below. 


specific  component  libraries 


lib tracked 
libsheeled 
librva 

libfva  libbalgun  libradar 

libmissile  libgenturret  libmlauncher  libvisual 

— — — - -  generic  component  libraries  - — -- — - - - 

libhulls  libturrets  libguns  libsensors 


architectural  library 
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libcomponants 


The  parametric  data  of  libcomponents  identifies  each  component  being  used  with  a  name  and  a 
model  number.  Optionally,  some  components  also  list  what  capabilities  that  component  provides 
to  the  vehicle  when  the  component  is  operational.  For  example,  a  T72M  component  entry  might 
look  like  this; 


(SM_Coinponents  (hull  SM.Track«dHull  SAFCapabilityMobillty) 
(turret  SM_GenericTurret) 

(machine-gim  [SM.BallisticGun  I  03  SAFCapabilityFirepovar) 
(main-gun  CSH_Balli8ticGun  I  1]  SAFCapabilityFirepovar) 
(visual  SM.Visual)) 


The  specific  parameters  used  by  each  component  are  listed  separately 


(SN_TrackadHull  (fflaz_speed  . . . )  . . . ) 

(SM_GenericTurret  (mu^slev  ...) 

( [SM.Balli8ticGun  I  0]  (round. types  munition_USSR.30mm)  ...) 

( tSM_BallisticGun  I  1]  (round. types  ffiunition.USSR.125HEAT 

munition.USSR.125SAB0T)  ...) 

(SN_Vi8ual  (max.detectable  . . . )  . . . } 


The  T72M  whose  component  entry  was  displayed  above  will  require  one  libhull,  one  libturret, 
and  one  libvisual  instantiation.  It  will  require  two  Ubgun  instantiations;  one  for  the  machine 
gun  and  one  for  the  main  gun.  The  specific  component  library  instantiations  will  be  instances  of 
the  generic  component  library  class.  This  component  class  relationship  for  the  libraries  currently 
implemented  is  shown  below. 


Instamtiations  of  Belong  to  generic  Have  a  command 

of  the  library:  cosiponent  class:  interface  defined  in: 


libtracked 

hull 

libhulls 

libvheeled 

hull 

libhulls 

librva 

hull 

libhulls 

libfva 

hull 

libhulls 

libmissile 

hull 

libhulls 

libgenturret 

turret 

libturrets 

libbalgun 

gun 

libguns 

libmlauncher 

gun 

libguns 

libvisual 

sensor 

libsensors 
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llbradar  sensor  libsensors 

An  application  issues  commands  to  a  specific  component  library  through  its  generic  component 
library.  For  example,  an  application  will  interface  to  libtracked  or  libfwa  through  libhulls  so  that  a 
tank’s  movement  control  commands  (which  are  performed  by  libtracked)  and  an  airplane’s  move¬ 
ment  control  commands  (which  are  performed  by  libfwa)  are  both  issued  via  the  interface  defined 
by  libhulls.  Similarly,  an  application  will  interface  to  libvisual  or  llbradar  through  libsensors. 

The  generic  component  libraries  define  the  common  set  of  functions  that  operate  in  the  specific 
component  libraries.  Each  generic  component  library  (such  as  libhulls,  libsensors,  libturret,  and 
libguns)  directs  libcomponents  to  define  a  component  class  for  itself  and  tells  libcomponents  the 
number  of  its  defined  functions.  This  information  enables  libcomponents  to  define  a  structure  that 
accommodates  all  the  components  of  an  object,  plus  it  allows  the  object’s  user  data  to  be  allocated 
enough  space  to  hold  the  address  of  each  function  defined  in  the  generic  component  library. 

The  interface  to  a  generic  component  library  is  defined  in  it’s  public  header  file  (such  as  lib- 
turret.h,  libguns.h,  libsensors. h,  and  libhulls.h.).  These  interfaces  allow  an  application  to  control 
(set)  or  learn  about  (get)  such  things  as  component  movement,  shooting,  and  sensing.  The  ap¬ 
plication  gives  a  command  to  an  objects’s  component  by  passing  a  macro  defined  in  the  generic 
component  library.  This  macro  identifies  the  function  which  needs  to  be  called.  For  example,  the 
macro,  HULLSJSETJDIRECTION^PEED,  will  result  in  the  invocation  of  the  specific  component 
function  named,  hulls^etjdirectionjspeed. 

When  a  function  is  to  be  called,  the  vehicle  id,  component  number,  and  function  pointer  index 
need  to  be  passed  to  libcomponents  so  that  the  appropriate  subclass  data  can  be  accessed.  The 
requested  function  needs  an  argument  list  to  handle  needed  input  (such  as  a  direction  or  speed) 
and/or  returned  output  (such  as  a  state  or  setting).  The  interface  structure  defined  in  the  generic 
component  library  defines  the  argument  list  which  is  passed  on  to  a  specific  component  library. 

Libcomponents  takes  care  of  the  following: 

•  Creating  the  components  listed; 

•  Associating  names  of  instantiations  with  user-data  handles,  for  those  libraries  which  support 
multiple  instantiations; 

•  Dispatching  calls  defined  by  the  generic  layer,  but  executed  by  the  specific  layer;  and, 

•  Creating  or  deleting  components  at  run  time. 

Creating/deleting  instantiations  also  impacts  the  tasks  which  use  those  instantiations.  For 
example,  a  task  which  looks  for  targets  wants  to  use  all  available  sensors.  Hence,  libcomponents 
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must  be  able  to  propagate  the  information  of  what  is  available  to  the  tasks  at  run  time.  This  is 
handled  as  foUows:  component  is  deleted /added,  libcomponents  calls  a  callback  routine  in  Ubsafobj, 
libsafobj  calls  functions  in  impacted  tasks.  This  facility  is  also  available  to  handle  damage/repair 
of  components  (libcomponent  provides  a  function  which  the  component-instance  sub-class  will  call 
when  it  is  damaged/repaired). 


Chapter  2:  Examples 


•  i 


2  Examp  les 


To  initialize  libhulls,  a  generic  component  class: 

cmpnt.def ine.clasB (SM.classHull .  HULLS.NUM.FUNCTIONS) ; 
To  initialize  Ubtracked,  an  instance  of  the  hull  class: 


track«d.u8er_data_handle  • 

class.reserve.usar.dataCparent.class,  "tracked",  tracked.print) ; 

/*  Tell  libcomponents  ee  are  available.  */ 

cmpnt.def ine.instance (SN_TrackedHull ,  1 ,  ttracked.U8er_data_handle , 

tracked. create,  tracked.deatroy, 
HULLS.SET.DI!lECTION.SPEED_FCN ,  set.dir.speed , 
HULLS.SET_VELOCITY_GEAR.FCN,  set.vel.gear, 
HULLS.SET_VELOCITY.DIRECTION.FCN,  set.vel.dir, 
HULLS.SET.VELOCITY.ORIENTATION.FCN,  aet.vel.ori , 
HULLS.SET.P0SITI0N.DIRECTI0N.FCN ,  8et.po8.dir , 

HUI LS,SET_G0AL_C0RRID0R.FCN,  8et.goal.corr, 
HULLS.SET_TARGET.ID.FCN,  set. target .id, 

HULLS .SET.TARGET.POSITIOH.FCM ,  eet, target. poeition , 
HULLS.GET_ETA.FCN,  get.eta); 


To  get  the  component  number  of  my  hull: 


extern  int32  my.hull; 

if  ((ny.hull  >  cmpnt.locateCvehicle.id,  reader_get_83nnbol("hull"})) 
CMPNT.NOT.FOUND) 

printf ("Vehicle  %d  doea  not  aeen  to  have  a  hull\n",  vehicle.id}; 

To  then  give  a  command  to  that  hull  (the  macro  is  defined  by  libhulls;  it  assembles  a  HULLS.INTERFACE 
structure,  and  calls  co^nt.invoke): 

if  (iiiy_hull  !-  CMPNT.NOT.FOUND) 

HULLS_SET_DIRECTION_SPEED(vehicle.id,  hull,  dirvec,  speed,  0.0,  0.0); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libcomponents,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  cmpntjnit 

void  cmpnt.initO 

cmpnt.init  initializes  libcomponents.  Call  this  before  calling  any  other  libcomponents  func¬ 
tions. 


3.2  cmpnt_define-class 

void  cDipnt.define.classCsaf.model.class,  nuacf unctions) 
uint32  saf .nodel.class ; 
int32  num_f unctions : 

^saf_iiiod«l_cla8s’ 

Specifies  the  class  being  defined 

‘nui&_f  unctions  ’ 

Specifies  the  number  of  functions  provided  by  that  members  of  the  class 

copnt.define. class  defines  a  class  of  component.  The  purpose  of  a  class  is  to  specify  the  func¬ 
tions  provided  by  components  of  this  class.  The  8af.Bodal.cla8S  is  one  defined  in  p^afmodels.h. 


3.3  cmpnt_define Jnstance 


void  cflipnt.dafina.instancaCsaf.TOdal,  nuBi.handla8 ,  handles, 

create,  destroy, 
function.nuiBber,  function, 
function_nuiDber,  ftmction, 

...) 


ulnt32 


saf .model ; 
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int32 

int32 


CMPirr_CREATE 

CMPNT.DESTROY 

int32 

CMPNT.FUNCTION 


nuin_handl«a ; 
handles  [] : 
create : 
destroy: 

function.nufflber; 

function: 


‘saf .model’ 

Specifies  the  model  number  of  the  instance  (implies  a  class) 

‘nuffl. handles’ 

Specifies  the  number  of  user  data  handles  provided  by  the  instance  (will  be  >  1  if  the 
instance  is  multiply  instantiable  per  vehicle) 

‘handles’  Specifies  a  list  of  user  data  handles 
‘create’  Specifies  the  function  to  call  to  create  an  instantiation 

‘destroy’  Specifies  the  function  to  call  to  destroy  an  instantiation 
‘function.number’ 

Specifies  a  function  code  number  defined  for  the  class 

‘function’ 

Specifies  a  function  to  call  when  ^ven  that  function.number 


cmpnt.define.instance  defines  an  instance  of  a  component  class.  The  instance  has  a  SAF 
Model  number  (which  implies  a  class)  and  a  list  of  functions.  The  instance  also  informs  libcompo- 
nents  of  bow  many  times  it  may  appear  per  vehicle,  and  the  bandies  used  for  each  appearance. 

The  create  and  destroy  functions  should  be  of  the  form: 


void  createfvehicle.id,  user_data.handle,  params) 
int 32  vehicle. id ; 

int32  U8er.data.handle ; 

ADDR^S  params; 


void  destroyCvehicle.id,  user_data.handle) 
int32  vehicle. id; 
int32  U8er.data.handle; 


Each  function  should  be  of  the  form: 


void  functionCvehicle.id,  U8er_data.handle.  parameters) 
int32  vehicle,  id; 

int32  U8er_data.handle; 

<CLASS>.IIfTERFACE  parameters; 
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3.4  cmpnt_classJinit 


void  cmpnt.class.init (parent. class,  availability.fcn) 
CLASS.PTR  parent. class ; 

CMPNT.AVAILABILITY  availability.fcn; 


^parent.class' 

Class  of  the  parent  (declared  with  class.declare.class) 

‘availability.fcn’ 

Specifies  the  function  to  call  when  component  availability  changes 

empnt. class. init  creates  a  handle  for  attaching  components  class  information  to  vehicles.  The 
parent jclass  is  one  created  with  class jdeclarc.class. 

The  availability.fcn  should  be  of  the  form: 

> 

void  availability (vehicle.id,  coioponent. number,  is.available) 
int32  vehicle.id; 
int32  component. number; 
int32  is.available: 

Note  that  this  function  is  not  called  at  vehicle  creation  (when,  technically,  components  first 
become  available). 


3.5  empnt^reate 


void  cmpnt.create (vehicle. id,  paxms,  name.symbol) 
int32  vehicle.id; 

COMPOHEHTS.PARAI(ETRIC.DATA  eparms; 
char  •name.symbol ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘parms’  Specifies  the  initial  paraitif'trr  values 
‘name.symbol’ 

Specifies  the  name  «»f  the  vflm  being  created  (such  as  ''vehicle.US3Il"). 


cmpnt.create  creates  the  rl.i>s  information  for  a  vehicle  and  attaches  it  to  the 
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vehicles  libclass  user  data.  It  also  creates  the  components  listed  in  its  parametric  data.  The 
nane.synbol  should  be  a  libreader  symbol. 


3.6  cmpnt_destroy 

void  cmpnt_de8troy(vehicle.id) 
int32  vehicle.id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 


ca^nt. destroy  frees  the  components  class  information  for  a  vehicle.  It  also  frees  any  componen  l 
instantiations. 


3.7  cmpnt_available 


void  capnt.available(vehicle.id,  saf. model,  is.available) 
int 32  vehicle. id ; 
uint32  saf. model; 
int32  is.available: 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘saf  .model’ 

Specifies  the  model  going  on/off  line 
‘is.available’ 

Specifies  whether  new  availability 

cmpnt.available  informs  libcomponents  that  the  component  is/isn’t  available.  Libcomponents 
passes  this  information  on  to  its  parent  (such  as  safobj)  which  tells  users  of  that  component  it  is 

available,  or  not  to  use  it.  Components  which  have  been  marked  as  unavailabile  will  not  be  able  to 
be  located  via  csqpnt. locate. 


3.8  cmpntjocate 
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int32  caqpnt.locateCvehicle.id,  specific.name) 
int32  vehicle. id; 
char  especific.naae; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘specific.name’ 

Specifies  the  name  of  the  desired  component 

cnpnt.locate  finds  the  component  number  of  a  specific  component  name  (the  name  should 
be  a  libreader  symbol).  This  number  is  then  used  in  calls  to  cnpnt. invoice.  The  return  value 
CMPNT.MOT.FOUND  is  returned  when  no  instance  of  the  passed  name  can  be  found.  Components 
which  have  been  marked  as  unavailabile  by  cmpnt.available  will  not  be  able  to  be  located  and 
wiU  return  CMPNT.HOT.FOUND. 


3.9  cmpnt.get Jnfo 


void  copnt.get.infoCvehicle.id,  component. nuaber,  specif ic.nBme,  8af.model) 
int32  vehicle.id: 
int32  coBiponent. number: 

char  **8pecific.name; 
uint32  vsaf .model; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘coa^nent.number’ 

Specifies  the  component 
‘specif  ic.name’ 

Returns  the  name  of  the  component 

‘saf .model’ 

Returns  the  model  number  of  the  component  (from  ‘p.saf models. h’). 
CB^nt.get.info  gets  the  name  and  SAF  model  number  of  the  specified  component. 


3.10  cmpntJnvoke 


void  CB^nt.invoke(function.number,  vehicle.id. 
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cooponent.number,  interface.block) 
int32  functioii.numb«r; 
int32  vehicle. id; 
int32  cooponent.nunber; 

ADDRESS  interface.block; 

’function_nuinber’ 

Specifies  the  function  to  call 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘coBtponent.nuBber’ 

Specifies  the  component  to  invoke  upon 

‘interface.block’ 

Specifies  a  pointer  to  a  block  of  parameters 


cmpnt.invoke  calls  the  specified  function  for  the  specified  component.  The  interface.block 
is  defined  by  the  component  class  header  file.  Note  that  the  class  header  file  generally  provides 
macros  which  prepare  the  parameters  and  invoke  this  function. 


3.11  cmpnt  Jocate  Jbymodel 


void  cnpnt.locate.bymodeKvehicle.id,  8af_model,  list.size,  list) 
int32  vehicle.id: 
uint32  saf. model; 
int32  elist.size; 
int32  listQ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘saf  .model’ 

Specifies  the  class  and  instance  part  of  the  SAF  model,  for  instance,  SN. Visual 

‘list.size’ 

Specifies  the  size  of  the  passed  list  array 
Returns  the  number  of  components  found 

aq>nt.locats.bymodel  finds  all  components  with  the  specified  saf. model  class  &  instance. 
The  size  of  the  passed  list  should  be  passed  in  slist.size.  The  number  of  components  found  is 
returned  in  slist.size. 
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3.12  cnipnt_get-capabilities 

uint32  cii^nt_get_capabiliti«s(v«hicle_id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

cmpnt.get.capabilitiee  finds  all  the  capabilities  enabled  on  a  vehicle  as  determined  by  having 
available  components  with  those  capabilities,  as  specified  in  the  components  parametric  data. 
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1  Overview 


There  are  many  coordinate  systems  used  to  describe  locations  on  the  earth.  Libcoordinates 
provide  a  facility  to  translate  between  any  of  the  following  coordinate  systems: 

COORD.CHARACTER-STRING 

Pretty-printed  version  of  one  of  the  other  coordinate  systems.  You  can  only  convert  to 
(not  from)  this  system. 

COORO.GCC 

Geocentric  coordinates.  This  is  a  right-handed  3D  cartesian  system,  with  Z  through  the 
north  pole  and  X  through  the  prime  meridian  at  the  equator.  It  assumes  the  WGS84 
ellipsoid  model  of  the  earth.  This  is  the  coordinate  system  used  in  DIS. 

COORD.TCC 

Topocentric  coordinates.  This  is  a  right-handed  3D  cartesian  system,  centered  around 
a  given  point,  with  Z  going  up,  positive  X  east,  and  positive  Y  north.  The  system 
can  either  be  derived  from  UTM  data  (as  SIMNET  terrain  databases  have  been;  often 
called  the  flat-earth  approach)  or  from  GCC  data  (often  called  the  curved-earth  drop-off 
approach). 

CQQRD.LATLQM 

Geodetic  coordinates.  This  is  the  latitude  and  longitude  system  used  by  the  air  force, 
navy,  and  meteorologists.  Note  that  altitude  is  not  measured  from  sea  level,  but  rather 
from  the  reference  ellipsoid.  Latitude  and  longitude  can  be  with  reference  to  the  map¬ 
ping  datum  used  at  that  location,  or  with  reference  to  the  WGS84  ellipsoid. 

C00RD.UTH.1IE 

Universal  Transverse  Mercator  projection  coordinates.  In  this  system  the  earth  is 
sliced  into  6  degree  wide  sections  (called  zones),  and  the  terrain  in  each  is  flattened 
out.  A  location  on  a  slice  is  identified  with  a  northing  which  indicates  distance  from  the 
equator  in  meters,  and  an  easting  which  indicates  distance  from  the  center  of  the  zone. 
Note  that  when  converting  from  UTM  to  Geodetic  (which  is  the  first  step  in  getting 
to  GCC),  the  altitude  is  not  changed.  This  is  not  entirely  correct,  since  the  UTM 
system  increases  the  altitude  at  the  edges  of  a  zone,  and  decreases  it  in  the  middle. 
The  algorithms  to  do  this  altitude  adjustment  have  not  been  built  into  libcoordinates. 

C00RD.UTM.GRID 

MilGrid  coordinates.  This  is  a  shorthand  notation  expressing  a  UTM  northing  and 
easting  in  terms  of  a  map  sheet,  and  an  o&et  into  that  map  sheet. 

An  added  complication  to  these  systems  is  the  fact  that  different  parts  of  the  earth  are  mapped 
using  different  assumptions  about  the  earth's  size.  First,  there  is  the  assumption  about  the  shape 
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of  the  earth,  which  is  called  the  spheriod  model.  There  are  13  different  models  currently  in  use. 
Second,  there  is  the  assumption  of  the  location  of  the  center  of  the  earth,  which  together  with  a 
spheroid  is  called  the  datum  (there  are  40  of  these).  The  data  file  ’coordinatea . rdr’  specifies 
Molodenskiy  parameters  for  each  datum,  which  allows  the  software  to  translate  point  mapped  with 
each  datum  to  the  corresponding  point  given  the  current  earth  model  (WGS84).  The  file  also 
specifies  which  datums  are  used  in  what  parts  of  the  world.  Finally,  the  file  gives  the  map  sh^et 
code  letters  used  by  the  MilGrid  system  in  different  places. 

This  data  file  is  not  complete  —  it  only  covers  a  small  portion  of  the  earth.  The  instructions  for 
adding  descriptions  of  new  areas  to  this  file  are  contained  in  a  header  at  the  top  of  the  file.  Two 
shell  scripts  (^r«ct’  and  ‘bounds’)  are  maintained  within  this  library  to  assist  in  generation  of  the 
data  file. 
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2  E  xam  p  les 


To  define  the  TCC  for  Ft.  Knox: 


•include  <libctdb.h>  /*  For  datun  definition  */ 

COORD.TCC.PTR  knox  •  coord_dofine_tcc(COORD_UTM_NE, 

4155000,  545000,  16,  'S’, 
DATUM_C01fUSllAD27, 

75000,  50000); 


To  get  the  MilGrid  designation  of  the  southwest  corner  of  that  database: 


char  buf [20] ; 
int32  ret; 
float64  z; 

if  (ret  ■  coord_convert(COQRD_TCC, 

knox,  0.0,  0.0.  185.0, 
CQQR0.UTM_GRID. 

CQORD_DEFAULT.ZO!fE.  8,  buf,  tz)) 
printf  C'XsXn" ,  convert.error(ret) ) ; 


To  get  the  GCC  coordinate  of  the  southwest  comer  of  that  database: 


int32  ret; 
float64  X,  7,  z; 

if  (ret  ■  coozd_convert(CQ0RD_TCC, 

knox,  0.0,  0.0,  185.0, 
COORD.GCC, 

Jtx,  Aj.  ftz)) 

printf ("XsXn" ,  convert_error(ret) ) ; 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libcoordinates,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  coordJnit 


int32  coord.init (directory,  flags) 
char  *dir«ctory; 
uint32  flags; 


‘directory’ 

Specifies  the  directory  where  the  constants  file  is  expected 
‘flags’  Specifies  reader  options  (see  section  ‘reader_read’  in  LibReader  Programmer’s  Manual) 


coord.init  initializes  libcoordinates,  causing  it  to  read  its  data  file  (coordinates.rdr)  either  from 
‘.’or  the  specified  director.  The  rsader.flags  are  as  in  reader.raad.  The  return  value  is  zero  if 
the  read  succeeds,  or  one  of  the  Ubreader  return  values  (READEILREAD.ERROR  READER.FILE_NOT_FOUND) 
if  it  fails. 


3.2  coord _define_tcc 


COORD. TCC.PTR  coord_dafine.tcc(80urc«.8y8t«n, 

origin.northing,  origin. ea8ting, 
origin.zone.nuDb«r,  origin.zone.letter, 
iiiapping.datuiii, 

databaze. width,  databaze.height) 

COORD.SYSTEN  zource.zyztem; 
float64  origin.northing; 

float64  origin.«a8ting; 

int32  origin.zon«.ntimb«r; 

int32  origin.zon«.letter; 

int32  mapping. datua; 

int32  databaae.nidth; 

int32  databaza.hsight; 

‘zource.zyztam’ 

Specifies  the  underlying  system  of  the  topocentric  coordinate  system 
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’origin.northing’ 

Specifies  the  northing  of  the  southwest  corner  of  the  TCC 
’orlgin_easting’ 

Specifies  the  easting  of  the  southwest  corner  of  the  TCC 
‘origin_zone_number’ 

Specifies  the  zone  number  of  the  southwest  corner  of  the  TCC 
‘origin_zone_l«ttar’ 

Specifies  the  zone  letter  of  the  southwest  corner  of  the  TCC 
‘mapping,  datum’ 

Specifies  the  datum  in  which  the  TCC  data  is  mapped  (only  used  if  source.system  is 

UTK_HE) 

‘database.vidth’ 

Specifies  the  east-west  size  of  the  TCC  system  (in  meters) 

‘database.height’ 

Specifies  the  south-north  size  of  the  TCC  system  (in  meters) 

coord. d«f  in*. tcc  defines  a  "topocentric"  coordinate  system  (centered  around  a  given  location, 
at  which  Z  is  up,  X  is  east,  and  Y  is  north).  The  source.system  must  be  either  COORD.GCC  or 
C00RD.UTM.HE.  GCC  derived  TCC  systems  curve  "down”  in  their  Z  values  as  distance  increases 
from  the  center  point.  UTM  derived  TCC  systems  are  completely  flat.  It  is  significantly  cheaper 
to  convert  TCC  coordinates  to  or  from  the  system  from  which  it  was  derived  than  to  or  from  the 
other  system.  Use  the  returned  pointer  in  calls  to  coord.convert. 


3.3  coord.estimate_tcc 


COORD.TCC.PTR  coord.estimate.tcc (source.system, 

latitude.hun.sec,  longitude.hun.sec, 
origin.utm.grid , 

database.vidth,  database.height) 

COORD.SYSTEN  source.system; 
int32  latitud*.hun.s*c; 

int32  longitude.hun.sec; 

char  *origin.utm.grid; 

int32  database.vidth; 

int32  database.height; 

‘source.system’ 

Specifies  the  underlying  system  of  the  topocentric  coordinate  system 
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‘latitud«_hun_8«c’ 

Specifies  the  latitude  of  the  southwest  corner  of  the  TCC  in  hundredths  of  seconds 
*longitude_hun_sec’ 

Specifies  the  longitude  of  the  southwest  comer  of  the  TCC  in  hundredths  of  seconds 
'origin,  utoi.  grid’ 

Specifies  the  UTM  grid  specification  of  the  southwest  comer  of  the  TCC 
‘database.width’ 

Specifies  the  east-west  size  of  the  TCC  system  (in  meters) 

‘database.height’ 

Specifies  the  south-north  size  of  the  TCC  system  (in  meters) 

coord.e8tiinat«.tcc  makes  a  reasonably  accurate  guess  at  the  TCC  parameters,  based  upon 
commonly  known  information. 


3.4  coord .tcc.gccj:otation 

int32  coord.tcc.gcc.rotation(tcc ,  matrix) 

C00RD.TCC.PTR  tcc; 
float64  matrixes] [3] ; 

‘tcc’  Specifies  the  TCC 

‘matrix’  Returns  the  TCC  to  GCC  rotation  matrix 

coord. tcc.gcc.rotation  fills  in  the  passed  3x3  TCC  to  GCC  rotation  matrix  based  upon  the 
GCC-derived  tcc  (the  GCC  to  TCC  matrix  is  the  transpose  of  the  returned  matrix).  The  return 
value,  if  non-zero  indicates  that  an  error  occured.  Passing  a  UTM  J^E-derived  TCC  will  yield  an 
error  (the  correct  rotation  from  UTM  to  GCC  is  dependent  upon  the  UTM  location). 


3.5  coord^onvert 


int32  coord. convert (from.878tem,  values...,  to.system,  values...) 
COORD.SYSTEM  from.system; 
values . . . ; 

COORD.SYSTEH  to.system; 
values . . . : 


8 


LibCoordinates  Programmer’s  Guide 


’lrom_sy8te]B’ 

Specifies  the  system  to  convert  from 

‘to.system’ 

Specifies  the  system  to  convert  to 

coord_convert  takes  two  sets  of  arguments  —  from_systen  and  to.system.  Each  system  has 
a  unique  code  and  a  series  of  values: 

COORD.CHARACTER_STIlIHG 

string 

COORD.GCC 

X  y  z 

COORD.TCC 

tcc^tr  X  y  z 
COORD.LATLQN 

latitude  longitude  z  localjdatum 

CQORD.UTM.HE 

zone  northing  easting  z 

C00RD.UTM.GRID 

zone  resolution  string  z 

The  types  of  these  arguments  are  shown  in  the  following  table: 


var 

froa.type 

to.type 

units 

example 

x 

float64 

float64  * 

meters 

5000.0 

y 

float64 

float64  * 

meters 

5000.0 

z 

float64 

float64  * 

meters 

283.0 

zone 

int32 

int32  « 

38  or  C00IlD.DEFAULT.Z0NE 

northing 

float64 

floated  * 

meters 

500000.0  (+N  -S) 

easting 

float64 

floated  * 

meters 

500000.0 

resolution 

int32 

int32 

digits 

3  — >  ES450550 

latitude 

float64 

floated  * 

degrees 

39.0  C+H  -S) 

longitude 

floated 

floated  * 

degrees 

42.0  (+E  -W) 

local.datum 

int32 

TRUE/FALSE 

tcc.ptr  COORD.TCC.PTR 

string  char  * 

Note:  UTH_GIIID  resolution  is  ignored  for  froB.8y8tem 

Explicit  zone  in  UTM_GRID  etring  overridee  paeeed  zone 
local.datunFFALSE  inpliee  to  uee  HGS84,  ae  eith  GPS 
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Non-zero  return  values  indicate  the  following  errors: 
COORD.SYNTAX 

Character  string  not  of  correct  format 
COORD.TOO.LONG 

Too  many  mllgrid  digits  passed 

COORD_ZONE_UNKNOWN 

Milgrid  in  unrecognized  I'TM  zone 

COORO.GRID.UNKNOWN 

Milgrid  grid  not  recognized  in  I'TM  zone 
C00RD_BAD_TCC 

Passed  TCC  pointer  in\'alid 
C00IU).SYSTEH_UMKN0WN 

Either  to^ystem  or  from.system  is  not  recognized 


3.6  coord_error 

char  *coord_arror(coda) 
int32  coda; 

‘coda’ 

coord_arror  returns  a  string  describing  the  error  code  returned  by  coord_conTarc. 


3.7  coord ^enerate..^rid 


void  coord.ganarata_grid(tcc,  ain.z,  maz.z,  min.y,  max.y, 

spacing,  digits,  labal.mask, 

■az.thin.sagsants ,  naz_thick_8agmant8 ,  maz_labels , 
n.chin.sagaants,  thin_8egmants , 
n.thick.sa^ants,  thick.sagmants , 
n. labels,  labels) 

COORD.TCC.PTR  tcc; 

int32  ain.z,  naz.z,  ain.y,  aaz.y; 

int32  spacing: 

int32  digits; 

uint32  labal.aask; 

i&t32  saz.thin.sagmants; 
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int32 

int32 

int32 

float32 

int32 

float32 


max. thick. segments ; 
max.labels ; 
*n.thin_segments ; 

thin_segments  □ ; 
*n_thick.segment8 : 
thick. segments  C3 : 


int32  *n.labels ; 

C00RD.GR1D.LABEL  labels []; 


‘tcc’  Specifies  the  TCC  of  the  grid 

’min_x,  max.x,  min_7.  max.y’ 

Specify  the  boundaries  of  the  grid  in  TCC  coordinates 

‘spacing’  Specifies  the  grid  line  spacing  (typically  multiples  of  10) 

‘digits’  Specifies  the  number  of  di^ts  with  which  to  label  grid  lines 

‘label_ma8k’ 

Specifies  thv>  sides  to  label 

‘msoc_thin.8egment8 ,  max_thick.segments .  max.labals’ 

Specifies  the  sizes  of  the  three  passed  arrays 

‘n_thin.8egment8,  n.thick.8egmant8 ,  n.label8’ 

Returns  the  number  of  returned  data  items  in  each  array 

‘thin.8egmants’ 

Returns  a  flat  list  of  n.thin.8egment8  X/Y*>X/Y  line  segments 
‘thick_8egment8’ 

Returns  a  flat  list  of  n_thick.8egment8  X/Y>>X/Y  line  segments 
‘labela’  Returns  a  list  of  labels 


coord.g8nerate_grid  takes  bounding  points  in  TCC  coordinates  and  generates  two  lists  of  line 
segments  (thin  and  thick)  which  form  a  grid  with  the  specified  spacing,  and  a  list  of  text  strings 
which  can  be  used  to  label  the  grid.  Note  that  up  to  4  *  max_tbin.8egment8  may  be  stored  in  the 
thiiusegments  array. 

lab8l.Bia8k  indicates  which  sides  to  label  with  an  inclusive  OR  of  the  following  masks: 


•  COORDJ.ABELJ,EFT 

•  COORDJ.ABELJUGHT 

•  COORDJ.ABEL.TOP 

•  COORDJ.ABELJOTTOM 


The  special  mask  COORD.LABEL.ALL  is  the  OR  of  all  of  these. 
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Labels  are  specifies  with  the  following  structure: 


typedef  struct 

< 

/*  The  location  of  the  label  in  TCC  coordinates  •/ 
int32  z.  y; 

/*  Null-terminated  label  string  *! 
char  tztCCOOItD.MAX_GRIO.LABEL_TZT]  : 

>  COORD.GRID.LABEL: 


3.8  coord -ide8cribe_xlatums 
▼oid  coord.describe.datufflsO 


coord_describe_datums  prints  descriptions  of  ail  known  datums  (from  table  read  in 
coord_inlt). 


3.9  coord .Jorm at Jatlon 


char  «coord.fozmat.latlon(latitude,  longitude) 
float64  latitude; 
float64  longitude; 


‘latitude’ 

Specifies  the  latitude 

‘longitude’ 

Specifies  the  longitude 


coord.fozBat_latlon  returns  a  pointer  to  a  character  buffer  which  has  the  passed  lat/long 
represented  as  ASCII  text.  The  buffer  is  static,  so  only  one  invocation  per  argument  list  is  allowed. 


3.10  coord-fixed.4>oint^egrees 

int32  coord_f ized_point_degrees (degrees) 
float64  degrees; 
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‘degrees'  Specifies  an  angle  in  degrees 

coord_fixed_point.degrees  returns  an  integer  which  is  the  passed  number  of  degrees  in  a 
DDMMSSHH  format. 


3.11  coord  _floating_point_degree8 

f loat64  coord_f loating_point_degrees (ddomsshh) 
int32  ddomsshh; 

‘ddnnnashh’ 

Specifies  the  encoded  number 

cooxd.f  loating_point_degrees  decodes  DDMMSSHH  format  into  simple  degrees. 

3.12  coord^iarse Jixed_point^egree8 

int32  coord.parss.fizsd_point. degress (string) 
char  estring: 

‘string’  Specifies  a  string  in  DDMMSSHH  format 

coord_parse_fized.poiat_degrees  parses  character  string  to  generate  DDMMSSHH  format 
fixed  point  integer. 


3.13  coord jcountjutm^ones 


void  coord.count.uta_zonos(tcc_ptr,  n.zones,  base.zone) 
COORD.TCC.PTR  tcc.ptr; 
int32  *n.zones ; 

int32  ebaso.zono; 


‘tcc.ptr’  Specifies  the  TCC 
‘n_zones’  Returns  the  number  of  zones 
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‘base.zone’ 

Returns  the  number  of  the  lowest  zone 

coord.count_utB_zones  returns  the  number  of  utm  zones  covered  by  the  database  TCC,  and 
the  number  of  the  lowest  zone. 


3.14  coordjookup^atum _by^e 


int32  coord_lookup_dattuB_b7_ne(zone.  northing,  easting) 
int32  zone ; 
floated  northing: 
floated  easting: 


‘zone’  Specifies  the  zone 
‘northing’ 

Specifies  the  northing 
‘easting’  Specifies  the  easting 

coord_loolnip.datua.by_ne  returns  the  DMA  suggested  mapping  datum  for  a  particular  loca* 
tion. 


3.15  coord Jookup^oneJetter 


char  coord.lookup.zono.letter(zone,  northing) 
int32  zone; 
floated  northing: 


‘zone’  Specifies  the  zone 
‘northing’ 

Specifies  the  northing 


Given  a  zone  &  a  northing,  coord_lookup.zone.letter  looks  up  the  correct  letter  designation. 


3.16  COORD_LATLONG_TO_GRID-ZONE 
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int32  COORD.LATLOHG.TO.GRID.ZOHEClatitude,  longitude) 
float64  latitude; 
float64  longitude; 


’latitude’ 

Specifies  the  latitude 

‘longitude’ 

Specifies  the  longitude 

Given  a  latitude  &  longitude,  the  macro  CQORO.LATLONG.TO.GRID.ZOHE  determines  the  UTM 
zone  number  in  which  that  coordinates  re^idos.  With  the  exception  of  a  couple  of  anomalies,  the 
world  is  broken  up  into  6  degree  wide  slices. 


3.17  COORD_WEST_LONG_OF_GRID_ZONE 

floated  COORD.WEST.LONG.OF.GRIO.ZONECzona) 
int32  zona; 

‘zona’  Specifies  the  zone 

Given  a  grid  zone  (in  the  range  1  through  60),  the  macro  COORD. UEST.LOHG.OF.GRID.ZOHE 
returns  the  longitude  of  the  western  edge  of  that  zone  at  the  equator. 


3.18  COORD JEAST-LONG-OF_GRIDJONE 

floated  C00R0.EAST.L0NG_0F.GRID_Z0RE(zona) 
int32  zona; 

‘zona’  Specifies  the  zone 

Given  a  grid  zone  (in  the  range  1  through  GO),  the  macro  C00R0_EAST.L0NG_0F.GRID.Z0HE 
returns  the  lonptude  of  the  eastern  «sige  of  that  zone  at  the  equator. 
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1  O  vervie w 


Libcreate  provides  the  following  services  for  simulated  ModSAF  entities: 

•  distributed  creation  of  simulated  entities  with  load  balancing  between  computers  of  the  same 
sifflulatorType  (such  as  simulatorJ-L-SAFSIM,  a  type  that  indicates  the  computer’s  ability 
to  simulate  entities) 

•  application  directed  handoff  of  simulated  entities  from  one  simulator  to  another 

•  fault-tolerant  takeover  of  simulated  ModSAF  entities  belonging  to  a  simulator  of  a  similar 
siotulatorType  when  that  simulator  crashes  or  exits 

The  algorithms  used  to  provide  these  services  are  provided  in  the  next  chapter. 

Libcreate  works  by  attaching  obj  ect.changed  and  sinulator.gone  handlers  (see  section  ‘Events 
and  Event  Handlers’  in  LibPO  Programmer’s  Manual)  in  the  PO  database,  as  well  as  through  two 
interface  functions  to  deal  with  new  and  deleted  objects. 

When  a  PO  entry  indicates  that  a  unit  object  that  has  not  yet  been  simulated  and  that  entry’s 
"shonldBeSimulated’  field  is  set  at  TRUE,  then  libcreate  simulates  the  unit  via  the  following 
procedure. 

1.  Make  a  call  to  libsafobj,  telling  it  to  go  ahead  and  instantiate  the  corresponding  object  as  a 
local  vehicle.  The  unit_name  of  the  entry  (such  as  US  J'ldD)  matches  to  a  .rdr  file  (such  as 
US-Fl4D_params.rdr)  so  that  the  appropriate  configuration  files  are  read.  Libsafobj  returns  a 
vehicleJd  when  the  object  has  been  instantiated. 

2.  Set  the  simulated  entity  to  have  needed  data  (such  as  exercise  number,  location,  forcelD, 
marking,  and  appearance).  This  data  is  passed  to  libentity  from  libcreate  and  the  Unit  PO 
(libPO).  Next,  build  a  rotation  matrix  corresponding  to  the  direction  the  user  wanted  the  unit 
to  face,  and  set  the  simulated  entity  to  point  that  way. 

3.  Initialize  the  hull  component  of  the  safobj  by  having  the  hull  point  in  the  desired  direction 
and  by  assigning  an  initial  speed  of  zero. 

4.  Make  the  appropriated  changes  to  the  PO  to  reflect  that  this  object  has  been  simulated. 
(The  "simulated"  field  will  be  set  to  TRUE,  and  the  "shouldBeSimulated"  field  will  be  set  to 
FALSE.) 

5.  Make  a  call  to  libentity  to  activate  the  new  entity,  that  is,  have  it  start  broadcasting  packets. 

6.  Finally,  set  the  association  between  the  safobj  and  the  c2obj  by  mapping  the  safob j’s  vehicleJd 
with  the  c2obj’8  unit  PO. 
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2  Algorithms 


The  following  sections  describe  the  algorithmic  implmentations  of  the  load-leveling  creation, 
migration,  and  fault-tolerant  takeover  services  of  libcreate.  Each  algorithm  depends  on  the  fact 
that  every  ModSAF  simulated  entity  has  a  corresponding  Unit  Class  Persistent  Object  (PO)  cor¬ 
responding  to  that  simulated  entity.  The  Unit  Class  objects  provide  the  shared  state  variables 
between  simulators  that  are  used  to  arbitrate  who  will  simulate  an  entity  at  what  time.  Since 
the  persistent  Unit  Class  objects  will  in  the  steady  state  be  consistent  across  all  simulators,  the 
decision  of  what  simulator  will  simulate  what  entity  will  be  consistent  across  all  simulators.  Since 
the  persistent  Unit  Class  objects  can  survive  a  simulator  crashing,  the  simulated  entities  derived 
from  those  persistent  Unit  Class  objects  can  survive  a  simulator  crashing. 

Through  out  each  algorithm  description,  it  is  important  to  note  that  although  local  inconsisten¬ 
cies  concerning  a  PO  object  can  occur  temporarily  between  simulators,  over  time  each  simulator 
will  have  consistent  information  about  each  object  in  the  database. 

The  following  fields  in  the  Unit  Class  object  are  relevant  to  the  creation  process: 

shouldBt^.  'bated 

'Z  if  a  Unit  <  ;^>jS  object  should  be  simulated  as  a  simulation  entity 

simulated 

TRUE  if  a  Unit  Class  object  is  simulated  as  a  simulation  entity.  This  field  is  never  true 
if  shouldBeSifflulated  is  TRUE. 

simulator 

SifflulationAddress  of  the  simulator  which  currently  is  or  most  recently  has  simulated 
an  entity  corresponding  to  this  object 

simulationID 

VehiclelD  of  the  simulated  entity  corresponding  to  this  object 


2.1  Load  Leveling  Creation 

Given  an  object  A  in  which  shouldBeSimulated  «■  TRUE  and  simulated  >«  FALSE,  there  are 
three  cases: 

1.  If  simulator  is  not  HULL,  then  change  the  object  to  have  simulator  ■«  B,  where  B  is  the 
simulator  registering  the  least  simulation  load  in  it’s  periodic  simulatorPresentPDU.  Increase 
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your  local  notion  of  that  simulator’s  load  based  on  what  increased  load  you  would  incur  for 
that  vehicle. 

2.  If  simulator  is  you,  wait  for  a  small  amount  of  time  and  then  perform  the  maybe.create 
procedure. 

3.  If  simulator  is  not  you,  ignore  the  creation  which  has  been  selected  for  another  simulator. 


When  the  maybe.creats  procedure  is  executed,  if  you  are  still  the  selected  siniulator  for  that 
object,  and  the  object  still  wants  to  be  siinulated.  simulate  the  entity  and  set  shouldBeSimulated 
*  FALSE,  siimilat«d»TRUE,  and  simulationlD  to  the  id  of  the  newly  simulated  entity. 


If,  through  missed  PO  packets,  two  or  more  simulators  decide  to  simulate  entities  corresponding 
to  the  same  object,  all  but  one  of  the  simulators  will  end  up  destroying  the  entities  through  the 
process  of  migration,  described  below. 


2.2  Migration 

Given  an  object  A  in  which  Sinulated  «*  TRUE  and  SimulationlD  is  a  local  vehicle  and  simulator 
is  not  me,  this  indicates  a  request  for  me  to  release  my  vehicle  to  the  other  simulator.  To  do  this, 
deactivate  the  vehicle  with  a  deactivateReason  of  vehicleHandoff . 

Given  an  object  A  in  which  Simulated  TRUE  and  SimulationlD  is  a  remote  vehicle  and 
simulator  is  me,  this  indicates  a  request  for  me  to  take  over  a  vehicle  from  another  simulator.  To 
do  this,  create  a  local  vehicle  immediately,  reusing  the  simulationlD.  Activate  this  vehicle  (i.e., 
broadcast  vehicle  appearance  packets)  upon  a  short  delay  or  receipt  of  a  deactivatePDU  for  that 
vehicle  with  a  doactivateReason  of  vahiclaHudoff,  which  ever  occurs  first. 

Note  that  where  load*leveling  creation  does  load-leveling  at  the  time  that  simulated  vehicles  are 
created,  migration  can  be  used  to  do  l«Md-  leveling  after  creation. 


Also  note  that  it  is  not  safe  for  a  ]>r(u;ram  to  exit  soon  after  performing  a  migration  of  it’s 
units.  This  is  because  it  is  pn^oiMe  to  -tart  a  migration  to  a  simulator  that  has  crashed.  The 
source  simulator  performing  the  iniKraiioii  may  be  the  only  simulator  to  hear  about  the  simulator 
crashing  after  beginning  the  tniur-ition.  .iml  in  that  case,  the  source  simulator  is  the  only  simulator 
who  will  know  to  change  the  tinur.ition  <]<':■  filiation  via  the  Fault  Tolerant  Takeover  process. 
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2.3  Fault  Tolerant  Takeover 

Given  a  simulator  S  which  has  timed  out  of  the  database,  query  for  all  objects  U  in  which 
simulator  »  S  and  simulated  ••  TRUE.  For  each  of  those  objects,  set  simiilated  FALSE  and 
shouldBeSimulated  TRUE.  Perform  the  choose  operation  as  in  (see  Section  2.1  [Load  Leveling 
Creation],  page  3),  and  this  case  reduces  to  Load  Leveling  Creation. 


2.4  Defeating  Load  Leveling  Creation 

Not  all  simulated  vehicles  want  to  be  load-leveled  across  different  simulators.  For  instance,  some 
applications  may  want  all  the  vehicles  in  a  platoon  to  be  on  one  simulator.  This  can  be  accomplished 
via  creation  conventions  when  creating  unit  hierarchies  (task  organizations).  If  a  simulator  (or  user 
interface)  wants  a  unit  and  all  it’s  subordinates  simulated  on  the  same  simulator,  it  should  mark 
just  the  unit  with  shouldBeSimulated  ••  TRUE.  If  it  wants  any  subordinates  to  be  potentially 
created  on  other  simulators,  those  should  be  marked  as  shouldBeSimulated  »  TRUE.  When  a 
simulator  goes  to  choose  a  simulator  for  an  object  where  shouldBeSimulated  TRUE,  it  should 
scan  the  entire  PO  database  for  any  subordinates  where  shouldBeSimulated  FALSE.  All  those 
units  should  be  changed  to  have  the  same  simulator  simulate  them,  and  the  subordinates  should 
be  modified  to  have  shouldBeSimulated  ••  TRUE  once  the  destination  simulator  is  chosen. 
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3  Examples 


The  following  code  fragments  demonstrate  usage  of  all  Ubcreate  functions: 

/*  1.  Acquire  a  simulation  exercise. 

*  2.  Acquire  a  simulation  address,  siouaddr. 

*  3.  Determine  the  number  of  vehicles  this  simulator  can 

*  simulate,  and  take  the  inverse  of  that  number  to  csdculate 

*  a  loading  factor. 

*  4.  Determine  the  type  of  simulator  you  are,  typically  a 

*  simulator.LL.SAFSIM  (for  load-leveling  SAFsim) . 

«  5.  Determine  the  simulation  protocol  version  being  used. 

*  6.  Create  an  active  open  PO  database,  po.db. 

*  7.  Create  a  pachetvalve,  valve,  and  set  it  up  to  process  PO 

*  packets . 

*/ 

cr.init (po.db,  valve,  protocol, 
exercise,  siffl_addr,  simulator.type,  loading); 

/• 

*  Turn  on  creation  debugging. 

*/ 

cr_ debugging (TRUE) ; 

/» 

*  Change  all  (past,  present,  and  future)  my  created  vehicles  to 

*  a  new  exercise. 

*/ 

cr_change_exercise(ne«_ez) ; 
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4  Functions 


The  following  sections  describe  each  function  provided  by  libcreate,  including  the  format  and 
meaning  of  its  arguments,  and  the  moaning  of  its  return  values  (if  any).  The  algorithms  for 
load-leveling  creation,  migration,  and  fault-tolerant  takeover  are  described  in  (see  Chapter  2  [Al¬ 
gorithms],  page  3). 


4.1  crjnit 


void  cr_init(db,  8im_«zerclse.id,  sia.address,  sin.type, 
loading.factor) 

PO.DATABASE  «db: 

PV.VALVE.PTR  packet. valve; 

int32  sia_protocol.version; 

uintS  aiB.ezercise.id; 

SinulationAddress  sia.address; 

SinulatorType  sin. type; 

float32  loading.factor; 

db  an  open  active  PO  database 

packet. vsdve 

the  libpktvalve  valve  being  used  for  reading  and  writing  PDUs. 

8 in_protocol. vers ion 

the  version  of  the  SimulationProtocol  being  used  for  this  exercise. 

8iB_ezerci8e.id 

the  exercise  to  simulate  entities  on.  This  should  match  the  exercise  being  listened  to 
for  SimulationProtocol  packets  in  the  packet  valve. 

8 in.  address 

simulation  address  being  used  by  this  computer,  and  it  must  match  the  address  used 
when  db  was  opened. 

siin.t]rpe  the  type  of  simulator  that  ran  lie  chosen  to  simulate  entities 
loading.factor 

the  weight  that  one  vchirie  li.is  on  the  simulation  as  a  fraction  of  full  load 


cr.init  initializes  libcreate.  r.i'i-mg  it  iti  listen  for  new  and  changed  UnitClass  objects  in  the 
PO  database  and  to  respond  to  tlK^**  ui*j«Tts  with  local  creation  and  deletion  of  entities. 


10 


LibCreate  Programmer’s  Guide 


4.2  cr.jchange-exercise 

void  cr.chang«.«z*rci8*(BiB_«z«rcis«_id) 
uintS  8im.«z«rcisa_id: 

‘8iffl_«zarci8a_id’ 

Specifies  a  new  exercise  id. 

cr.chang8.«z«rci88  causes  all  locally  created  entities  to  change  to  a  new  exercise  and  forces 
all  newly  created  entities  to  be  created  in  the  specified  exercise. 


4.3  cr^ebugging 

void  cr.dcbugging(flag) 
int32  flag; 

‘flag’  Specifies  whether  or  not  debugging  statements  should  be  printed.  Has  either  TRUE  or 
FALSE  value. 

cr.dabugging  turns  debugging  print  statements  either  on  or  off,  according  to  the  flag.  When 
debugging  is  on,  indications  of  the  creation  process  are  printed  to  stdout. 


4.4  cr.jiew^bject 

void  cr.nov.objoct(db,  entry) 

PO.DATABASE  edb; 

PO.DB.EITRY  eentry; 

‘db’  A  Persistent  Object  database. 

‘entry’  A  new  Persistent  Object  entry  that  just  arrived  in  the  database. 

cr.nev.object  should  be  called  for  every  new  PO  entry.  If  the  entry  is  of  type 
objectClassUnit  and  it  should  be  simulated  as  a  simulation  object,  this  function  wiU  cause  the 
appropriate  entity  to  be  created. 
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4.5  cr_de8troy_ob ject 

void  cr.destroy.obj act (db, entry) 

PO.DATABASE  *db: 

PO.DB.EMTRY  *entry; 

‘db’  A  Persistent  Object  database. 

‘entry’  A  new  Persistent  Object  entry  that  is  about  to  be  deleted  from  the  PO  database. 


cr.deetroy .object  should  be  called  for  every  PO  entry  which  is  about  to  be  deleted.  If  the 
entry  is  of  type  objectClaesUnit  and  it  is  being  simulated,  this  function  will  cause  the  appropriate 
entity  to  be  deactivated  and  destroyed. 
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1  W  hy  Libctdb? 


The  Compact  Terrain  Database  library,  libctdb,  is  used  by  an  application  to  access  elevation, 
soil  type,  and  feature  data  of  a  SIMNET  database.  Terrmn  databases  are  compiled  from  SlOOO 
source  (or  other  source  formats)  into  libctdb  format.  Applications  use  libctdb  to  load  this  database 
into  memory,  and  then  use  libctdb  functions  to  access  the  data  therein. 

Libctdb  functions  include: 

•  Reading  the  database  into  memory  or  cache 

•  Maintaining  useful  information  about  the  database,  such  as  its  size,  minimum  and  maximum 
elevation,  and  UTM  zone,  northing  and  easting  (its  location  on  the  planet) 

•  Point  elevation  lookup 

•  Elevation  lookup  along  a  line  segment  (find  high  ground,  find  terrain  profile,  etc.) 

•  Soil  type  lookup 

•  Vehicle  placement  (rotation  matrix  generation) 

•  Intervisibility  calculation  (including  terrain  and  vehicle  blockage) 

•  Radar  clutter  calculation 

•  Generating  graphic  representation  of  the  terrain  such  as  contour  maps  and  hypsometric  maps, 
in  real  time 

The  CTDB  header  format  includes  a  flag  which  indicates  whether  the  database  was  generated 
assuming  grid  squares  break  along  diagonals  running  from  NW  to  SE  or  along  diagonals  running 
from  SW  to  N£.  The  library's  public  funtions  take  note  of  this  flag  at  invocation  and  apply  different 
internal  algorithms  accordingly  see  Chsq>ter  6  [Algorithms],  page  57. 

Libctdb  provides  several  advantages  over  other  terrain  access  libraries  used  in  the  past.  Some 
of  the  highlights  are  detailed  in  the  following  sections. 


1.1  Smaller  storage  requirements 

The  libctdb  terrain  database  file  format  uses  several  compression  methods  to  minimize  storage 
requirements.  The  resulting  files  are  one-sixth  to  one-twentieth  the  size  <ff  files  used  by  previous 
terrain  database  libraries.  In  addition  to  reducing  hardware  cost  associated  with  storing  these 
databases,  this  compression  allows  more  of  the  database  to  be  stored  in  main  memory  (improving 
performance  by  reducing  disk  access). 
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The  largest  savings  is  derived  by  exploiting  the  regular  nature  of  terrain  database  modeling. 
Most  elevation  data  is  obtained  from  the  Defense  Mapping  Agency  (DMA).  DMA  data  is  a  regular 
sampling  of  elevations.  The  sampling  interval  is  specified  as  “Level  1"  (90  meter  spacing)  or  “Level 
2”  (30  meter  spacing).  SIMNET  databases  are  built  from  this  data  as  follows: 


1.  The  DMA  data  is  down-sampled  to  125  meter  spacing.  This  is  done  using  linear  interpolation. 
We  refer  to  a  point  in  this  125  meter  grid  as  a  post. 

2.  Each  square  in  the  grid  is  broken  iot .  two  triangles  via  a  line  running  northwest  to  southeast: 
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and  each  triangle  is  assigned  a  soil  type. 

3.  The  grid  is  broken  into  p&tcbes  500  meters  on  a  side: 

I  I  I 

+  4  +  *  +  +  + 

I  i  I 

444444444 

I  I  I 

444444444 

I  I  I 

4-4-4-4-4-4-4-4-4 

Each  post,  therefore,  has  an  elevation  and  two  soil  types  (by  convention,  the  soil  types  of  the 
two  triangles  to  its  southeast).  The  libctdb  format  encodes  the  information  regarding  each  post 
(elevation,  two  soil,  and  some  flags)  into  a  32  bit  item.  Hence,  to  store  a  grid  the  size  of  the  Ft. 
Knox  database  (50  km  x  75  km)  requires  400  posts  x  600  posts  x  4  bytes  per  post  =  just  under  1 
MB.  The  posts  are  stored  in  such  a  way  that  the  post  for  a  particular  X,Y  location  can  be  found 
with  a  few  arithmetic  operations. 

In  addition  to  this  regular  grid  of  elevations,  some  areas  of  the  terrain  are  modeled  more  predsely 
using  microterrain.  Microterrain  is  a  collection  of  squares  and  triangles  which  cover  a  portion  of 
a  patch.  Libctdb  uses  an  original  algorithm  to  store  these  microterrain  polygons  in  a  compact 
fashion. 
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I 

) 

On  the  surface  of  the  terrain  axe  "buildings'*  (which  is  loosely  defined  to  include  pipelines  and 
i  other  opaque  non-penetrable  structures),  trees  (individual  trees,  tree  lines,  and  tree  canopies),  and 

linear  features  (roads  and  rivers).  For  each  patch,  the  microterrain  and  surface  features  (each 
encoded  in  a  compact  fashion)  are  stored  together. 

I 

Adding  features  to  the  Ft.  Knox  database  brings  the  total  storage  requirement  up  to  4.5  MB. 
By  contrast,  other  database  formats  typically  require  around  30  MB  to  store  Ft.  Knox.  The  large 
SAKI  database  (360  km  x  290  km)  requires  about  30  in  libctdb  format,  over  600  MB  in  other 
formats.  The  greater  compression  is  achieved  because  the  SAKI  database  is  mostly  desert,  and 
I  hence  relatively  free  of  features. 


1.2  More  efficient  disk  cache 

Although  libctdb  terrain  databases  are  relatively  small,  they  may  still  require  more  memory 
than  an  application  can  afford  to  ^ve  up.  The  solution  to  this  problem  is  the  use  of  a  disk  cache. 
Libctdb  uses  two  caches,  one  for  the  elevation  grid,  and  another  for  the  patch  features. 

When  an  application  loads  a  libctdb  database,  it  specifies  the  maximum  memory  which  can 
be  used  to  store  the  database.  This  memory  is  split  up  between  the  two  caches,  such  that  the 
probability  of  a  hit  is  the  same  for  each.  This  will  typically  result  in  more  memory  allocated  for 
the  feature  cache,  since  databases  will  usually  require  more  storage  for  features  than  for  elevations. 


1.2.1  Elevation  cache 

The  elevation  data  is  stored  using  a  technique  called  tiling,  in  which  the  large  rectangular  grid 
is  broken  into  equally  sized  sub-rectangles.  Each  sub-rectangle  (called  a  page)  is  a  square,  with  32 
posts  on  a  side  (4  km).  The  32  x  32  posts  require  4  Kb  of  storage.  Since  the  posts  are  grouped  into 
geographically  close  areas,  and  applications  wiU  typically  be  accessing  geographically  close  areas, 
cache  consistency  (the  probability  a  needed  page  is  in  the  cache)  will  be  high  for  most  applications. 

The  elevation  cache  is  a  direct  mapped,  fixed  size  cache.  That  is,  when  the  application  needs 
a  page  of  elevation  data  which  is  not  currently  in  the  cache,  it  is  loaded  into  the  cache  location 
paga_nuBb«r  MODULUS  cache.size.  The  page  numbers  are  assigned  in  east  to  west  (minor),  south 
to  north  (major)  order.  Such  a  caching  scheme,  runs  the  risk  of  thrashing  (consistently  missing) 
when  two  different  pages  which  happen  to  occupy  the  same  cache  location  are  needed  simulta¬ 
neously.  For  example,  if  the  database  is  20  pages  wide,  and  the  cache  size  is  20  pages,  running 
visibility  rays  due  north  wiU  cause  frequent  cache  misses.  To  avoid  this  problem,  the  caching  code 
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monitors  cache  performance,  and  when  thrashing  is  detected,  the  cache  size  is  lowered  by  one 
(within  reason). 


1.2.2  Feature  cache 

Feature  data  presents  a  different  problem.  Some  patches  have  ve**^  few  features,  others  have 
very  many.  The  quantity  of  feature  data  in  a  patch  is  referred  to  as  feature  density.  Measured  in 
4  byte  words.  Ft.  Knox  has  feature  densities  ran^ng  from  1  to  739  for  a  patch  group  of  4  adjacent 
patches  (grouping  patches  into  sets  of  four  is  a  technique  used  to  reduce  overhead).  Hence,  using 
a  single  cache  in  which  each  entry  can  hold  any  patch  (the  technique  used  for  the  elevation  cache) 
will  result  is  a  great  deal  of  internal  fragmentation  (wasted  space).  Instead,  during  compilation, 
each  patch  group  is  assigned  to  one  of  16  caches.  Each  cache  has  about  the  same  number  of  entries, 
but  the  size  of  each  entry  varies  by  cache  to  minimize  fragmentation. 


1.3  New  algorithms 

New  algorithms  have  been  developed  to  improve  performance  of  libctdb  functions.  The  key 
improvements  have  been  the  elimination  of  unnecessary  search,  the  use  of  more  efficient  methods 
for  several  key  routines,  and  the  judicious  use  of  approximation. 


1.3.1  Elimination  of  search 

Finding  an  elevation  on  the  regular  grid  does  not  require  any  search,  except  in  the  case  where 
microterrain  is  present. 

In  addition  to  elevation  and  soil  information,  each  post  in  the  regular  grid  has  bodean  flags 
which  indicate  the  presence  of  microterrain,  buildings,  trees,  or  other  features.  By  checking  these 
flags,  libctdb  can  avoid  searching  for  features  it  will  not  find.  In  the  case  of  NWJSE  diagonalization, 
the  flags  indicate  the  presence  of  features  in  the  square  to  the  southeast,  and  the  case  of  SWJIE 
diagonalization,  the  flags  refer  to  features  in  the  square  to  the  northeast  of  the  post. 

Furthermore,  each  feature  is  marked  with  a  bit  mask,  identifying  which  posts  it  crosses  within 
its  patch.  In  the  following  example,  each  post  within  the  patch  is  identified  by  the  hexadecimal 
digits  ‘0’  through  *F’.  A  road  is  drawn  with  the  symbol  *•’. 
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For  IV.SE  diagonalization: 
C-D-E-F-+ 

I  I  0000  «  0 

8  9  A  B  <•> 

I  •••!  1100  •  C 

4  S  687  ♦ 

I  •••  I  0110  •  6 

0  142  3  ♦ 

I  •  I  0010  >  2 

For  SH.VE  diagonalization: 

I  I  0000  •  0 

C  D  E  F  ♦ 

I  •••!  1100  •  C 

8  9  AfB  ♦ 

I  •••  I  0110  >  6 

4  586  7  ♦ 

I  8  I  0010  •  2 

0-1-2-3-+ 


Notice  that  the  post  mask  for  a  feature  turns  out  to  be  the  same  regardless  of  the  diagonalization 
of  the  underlying  grid.  The  road  covers  the  triangles  associated  with  posts  1,  5,  6,  A,  and  B. 
Hence  it  would  be  marked  with  the  flags  0x0C62.  Twenty>five  bits  are  reserved  for  this  mask  to 
accommodate  future  database  requirements.  A  function  finding  the  soil  type  of  a  pmnt  southeast  of 
post  6  and  northwest  of  poet  3,  could  eliminate  ail  roads  which  do  not  have  bit  6  set.  In  other  words, 
the  domain  of  feature  searches  can  be  limited  to  very  likely  candidates  with  only  one  arithmetic 
operation  per  feature. 


Another  critical  algorithm  which  has  been  coded  to  minimize  search  is  the  interviubility  algo¬ 
rithm.  Using  a  technique  borrowed  from  computer  graphics  called  dJgitaJuMtion,  rasterization,  or 
scan  conversion,  the  triangle  edges  which  cross  a  line  of  sight  ray  can  be  predicted  almost  exactly. 
In  the  fdlowing  example,  the  line  of  sight  ray  is  show  on  the  left  as  a  series  of  the  posts  deter¬ 
mined  to  be  involved  are  shown  in  the  middle  as  ‘8’,  and  the  edges  tested  are  shown  on  the  right. 
(Interior  posts  removed  for  clarity.) 
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As  the  posts  are  determined  by  the  rasterization  algorithm,  a  mask  can  be  assembled  which 
encodes  which  triangles  line  of  sight  crosses  (in  the  previous  example  it  would  be  ‘0x4462’).  This 
mask  can  be  compared  against  the  masks  associated  with  features  such  as  trees,  buildings,  and 
microterrain,  to  reduce  the  search  domain.  Also  the  feature  flags  associated  with  the  posts  traversed 
are  used  to  eliminate  entire  classes  of  features  which  could  not  possibly  have  interfered  with  visibility 
on  the  patch  being  tested. 


1.3.2  EflScient  implementations 

Many  often-invoked  routines  have  been  written  using  a  mathematical  construct  known  as  para¬ 
metric  equations,  in  which  coordinates  of  a  Une  are  described  by  simultaneous  equations  of  a 
common  parameter,  rather  than  one  in  terms  of  the  other.  A  line  segment  would  be  defined. 


*  =  /(<).  y-p(0.  0<t<l 


rather  than. 


V  *  /(*)»  ^min  S  *  S  Xtnmst  Imin  ^  V  S 


Not  only  is  it  less  expensive  to  solve  for  t  than  for  x  and  y  in  most  cases,  but  in  the  case  of 
intersecting  finite  line  segments,  the  pdnt  of  intmection  can  usually  be  determined  to  be  out  of 
bounds  (f  <  0,  or  <>  1)  before  it  is  actually  computed  ( t  will  typically  be  computed  tda  a  division, 
hence  the  range  of  t  can  be  determined  by  comparing  the  magnitude  of  the  numerator  versus  that 
of  the  denominator). 

In  addition  to  line/line  intersection  tests,  parametric  equations  are  also  used  to  improve  perfor¬ 
mance  of  linear  interpolation  and  pdnt /line  proximity  tests. 


Chapter  1:  Why  Libctdb? 
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l.S.S  Judicious  approxiTnation 

In  some  cases,  reasonably  accurate  approximations  are  used  rather  than  computing  the  exact 
answer.  The  most  notable  example  of  this  is  the  use  of  single  precision  square  root,  fsqrtO,  rather 
than  the  float64  precision  version,  sqrtO.  Also,  the  vehicle  placement  code  uses  an  approximation 
to  guarantee  the  rotation  matrix  generated  is  orthonormal,  avoiding  a  square  root  and  an  expensive 
matrix  operation. 


1.4  Optimized  for  RISC  processors 

The  libctdb  functions  have  been  ezteasively  profiled  and  tuned  to  yield  maximum  performance 
on  RISC  platforms.  The  types  of  optimizations  which  help  RISC  platforms  are  foreign  to  many 
programmers,  and  hence  are  rarely  performed.  The^  include: 

•  Avoiding  conversions  between  diflereat  numeric  formats  (integer,  single  precision  floating  pmnt, 
and  float64  precision  floating  point). 

•  The  use  of  float64  precision  floating  point  rather  than  single  precision  for  temporary  variables 
to  avoid  type  conversions  during  evaluation. 

•  Using  many  local  variables,  rather  than  small,  fixed  size  arrays  to  make  maximum  use  of  CPU 
registers. 

•  Using  multipfication,  rather  than  division,  wherever  possible. 

•  Judicious  use  of  static  global  variables  to  reduce  parameter  passing  overhead  in  function  invo¬ 
cations. 

•  Use  of  array  syntax  (aCi]),  rather  than  pointer  syntax  (•(a^i)),  in  cases  where  the  latter 
would  prevent  certain  optimizations  by  the  compiler. 

•  Use  of  if  ...  if  . . .  elae  if  chains  rather  than  svitcb  case  statements  when  the  num¬ 
ber  of  choices  is  small. 

Performance  tests  were  used  to  oonfirm  choices  of  syntax  in  all  cases. 


1.5  Improved  ir'^ervisibility  model 

In  addition  to  execution  sf  improvements,  the  fidelity  of  the  intervisibility  model  has  been 
significantly  improved.  The  new  model  incorporales: 
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•  Light  transmittance  model  used  Ibr  modeling  cumulative  effect  of  intervening  trees,  with  tree 
opacity  a  caller  specified  parameter. 

•  Use  of  both  target  width  and  height  (relative  to  the  viewer)  for  determination  of  visible  area 
(dder  models  used  height  only). 

•  Accurate  model  of  building  sizes  and  locations  (older  models  used  only  compass  aligned  bound¬ 
ing  box). 

•  Determination  of  visibility  as  an  analog  value  in  the  range  0  to  1,  rather  than  a  digital  Visi¬ 
ble/Partial/Blocked  resdt. 

•  Accurate  model  of  vehicle-bloddng-vehicle  visibility,  incorporating  width  and  height  (relative 
to  the  viewer)  of  intervening  vehicles. 

•  Reasonably  fast,  extremely  high  fidelity  rasterization  model  available,  which  can  determine 
exactly  whht  parts  of  a  vehicle  are  visible. 


1.6  More  thorough  documentation 

In  addition  to  this  document,  Cbctdb  is  documented  via  extensive  in-line  comments,  and  a 
documented  header  file. 


Chapter  2:  Examples 
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2  Examples 


The  following  programs  demonstrate  the  use  of  selected  libetdb  functions.  The  programs  were 
intentionally  kept  brief  for  clarity.  In  general,  a  program  should  declare  a  variable  of  type  ‘CTDB’ 
to  hold  header  information,  call  ctdb.raadC. . .)  to  initialize  this  structure,  and  then  call  other 
libetdb  functions  with  a  pointer  to  this  variable  as  thmr  first  argument. 


2.0.1  Elevation  Lookup 


The  following  program  reads  a  libetdb  format  database,  prints  information  in  the  database 
header,  and  finds  the  elevation  at  the  center  of  the  rhetabaae. 


/* 

*  File:  dbcantar.c 

* 

*  Coapilad  as  follows: 

* 

*  ec  *0  dbeantar  dbcantar.c  •I/comaon/iacludaAibiac  »L/cowon/llb  \ 

*  •letdb  -la 

*/ 

/*  Includa  this  bandar  in  all  f  ilea  rafacaaciag  Jlbctdb  functions , 

*  constants,  or  data  structuras. 

•/ 

•includa  Oibctdb.h> 

aainCarge,  srgv) 
int32  urge; 
char  eargrD: 

{ 

CTDB  etdb;  /a  Allocata  storaga  on  tha  stack  for  tha  databasa 
a  haadar.  Most  of  tha  nmory  usad  by  libetdb 
a  will  ba  allocatad  dynaatically  whan  tha  databasa 
a  is  raad. 
a/ 

float64  ■id.z,  ■id.y,  zd.d^; 

if  (arge  !-  2) 

i 

printfC'Usaga:  Xs  <fiIa-naM>\s*',  argrlOi]}; 
azitCO) : 

> 

/a  Bead  tha  databasa.  Allow  tha  library  no  nora  than  INB  of 
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*  storag*.  lota  that  if  an  arror  occurs,  libctdb  vill  call 

•  azit(l). 

•/ 

ctdb.raadCftctdb,  argtCl],  1«20}; 

/*  Print  a  description  of  tha  database. 

•/ 

ctdb.print.dascriptionCtctdb) ; 

/*  Find  tha  aidpoint  of  tha  database. 

•/ 

■id^  ■  (ctdb.Baz.x  *  ctdb.ain.z)  /  2.0; 

■id.y  ■  (ctdb.aaz.j  ♦  ctdb.Bin.j)  /  2.0; 

/*  Find  tha  alatation  at  that  point. 

•/ 

■id.z  ■  ctdb.lookup.olaYation(ftctd&,  aid.!,  aid_y); 

/*  Print  tha  result. 

•/ 

printfC “Canter  of  database:  <Xf  Xf  Xf>\n“, 
aid.z.  aid.y.  aid.z): 


2.0.2  Visibility  Testing 


The  following  program  reads  a  libctdb  format  database,  and  determines  visibility  between  two 
user  specified  points.  Libcoord  is  used  to  translate  the  user  specified  coordinates  from  UTM  to 
X,Y.  Libreader  is  used  to  read  the  libcoord  database. 


Note  that  information  in  the  CTDB  data  structure  can  be  used  to  initialize  libcoord. 


/• 

*  File:  Chris. c 
a 

*  Coaplled  as  follows: 

* 

*  cc  -o  Chris  Chris. c  •I/c(»BBoa/include/libinc  'L/canBon/lib  \ 

*  "Iccdb  -Icoord  'Ireader  -11 
•/ 

/*  Include  this  header  in  all  files  referencing  libctdb  functions, 

*  constants,  or  data  structures. 

•/ 

•include  <libctdb.h> 
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/*  Other  header  files  */ 

•include  <libreader.h> 

•include  <libcoord.h> 

/*  Typical  values  */ 

•define  EYE.1IEIGHT  2.0 
•define  TARGET.HEIGHT  2.0 
•define  TARGET. VIDTH  4.0 

•define  TREE.OPACITY  0.5  /•  Must  be  between  0.0  and  1.0  •/ 

nainCarge.  argv) 
int32  arge; 
char  aargrO: 

CTDB  etdb;  /*  Allocate  storage  on  the  stack  for  the  databoe 

*  header.  Host  of  the  mmoxj  used  by  libetdb 

*  will  be  allocated  dynaaically  when  the  database 

*  is  read. 

*/ 

DATA.UII0I  uta.file: 
int32  rec; 

float64  a7e.z,  eye.y.  eye.z; 
floated  targ.z.  targ.y.  targ.z: 
floated  wis; 

if  (arge  !•  d) 

< 

printfC "Usage:  Xs  <file>nane>  <eye  Unf>  <target  UTN>\n". 

argv[0]); 
ezit(O) ; 

> 

/*  Read  the  database.  Allow  the  library  no  nore  than  IMB  of 

*  storage.  Rote  that  if  an  error  occurs,  libetdb  will  call 

•  ozit(l). 

•/ 

ctdb.road(tctdb,  argv[l],  1«20): 

/*  Initialize  libcoord. 

•/ 

if  (reader.read.file("/saf/config/uta.lisp”,  tuta.file)  !■  0) 

< 

printf ("Error  reading  libcoord  databaseVn"); 
ezit(O) ; 

> 

coord.setjd.lgr  id.  table  (  uta.f  ile .  array) ; 
sianet.origin.northiag  •  ctdb.origin.northing; 

sinnet.origin.aaating  •  ctdb. origin. easting: 

sianet.origin.zone  «  etdb.origin.zone.nuBber; 

sianet.origin.zone.letter  ■  ctdb.origin.zone.letter; 
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■iaaet.datuB  ■  etdb.datun; 

/*  Canvert  user  aupplied  coordinates. 

•/  _ 

rot  ■  conTort.coordinatos (COORD .SYSTEM.UTMGRID, 

COORD.OEFAULT.ZOIE.  0.  argrCl]. 

C00R0.SYSTE31.SIiaiET. 

ftoyo.z,  ftoyo.j): 

if  (re^: 

{ 

printf ("Error  converting  UTM  Xa:  Xa\n", 
argvCl].  convert_error(ret)); 
ozit(O) ; 

> 

rot  ■  conTort.coordinatos (COORD.SYSTEM.UTMGRID , 

C00RD.DEFAULT.Z0IE.  0.  argT[2], 
COORD_SYSTDl.Sl)aET . 

Atarg.z,  fttarg.7): 

if  (ret) 

printf ("Error  converting  UTM  X*:  Xs\n", 
argvCZ] .  convert.erTor(ret)) ; 
ezit(O) ; 

> 

/*  Find  the  elevation  at  each  point. 

*/ 

eye^  ■  ctdb.lookup.elevation(tctdb,  eye.z,  eye.y); 
targ.z  •  ctdb.lookup_elevation(tctdb,  targ.z,  targ.y); 

/•  Cospute  visibility  using  typical  values. 

•/ 

vis  ■  ctdb.point.to_point(ftctdb, 

eye^,  sye.y,  eye.z, 
targ.z,  targ.y.  targ..z, 
t  arg.z«TAR(ZT.HEI(tBT , 
TAIUZT.tfZDTH, 

TREE.OPACITT, 

0.0,  /*  Coiiputs  even  if 
*  barely  visible. 

•/ 

0  /•  lo  vehicles  in  the 
•  vay. 

•/ 

); 


/*  Print  the  result. 

•/ 

printf("X5.2fXX\n",  100.0  *  vis); 
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3  Functions 

The  following  sections  describe  each  function  provided  by  libctdb,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  vaJues  (if  any).  Descriptions  of  how  each 
function  performs  its  task  can  be  found  in  the  algorithms  section.  See  Chapter  6  [Algorithms], 
page  57. 


3.1  ctdb^pparent-shape 

void  ct db_ apparent. shape (xO.  yO.  zO,  xl.  yl,  zl, 

rotation,  length,  width ,  height, 
app.loc,  zh.  x.min,  z.aiaz,  z_nin,  z.nax, 
proj,  dist,  object.correction, 
raster) 


float64 

xO,  yO,  zO; 

float64 

xl,  yl,  zl; 

float64 

rotationCS]  [3] : 

float64 

length,  width,  height: 

float64 

app.loc [3] ; 

float64 

*zh: 

float64 

«x.Bin: 

float64 

«x.nax; 

float64 

ez.Bin; 

float64 

*z.max; 

float64 

proj [3] [3] ; 

float64 

«dist: 

floatM 

*ob  J  oct .  correct  ion ; 

uint32 

raster [32] ; 

‘xO,  yO,  zO’ 

Specifies  the  location  of  the  viewer 
‘xl,  yl,  zl’ 

Specifies  the  location  of  the  target 

‘rotation’ 

Specifies  the  3x3  rotation  matrix  of  the  target 
‘length*  Specifies  the  length  of  the  target  (its  Y  dimension) 

‘width’  Specifies  the  wddth  of  the  target  (its  X  dimension) 

‘height’  Specifies  the  height  of  the  target  (its  Z  dimension) 

‘s^.loc’  Returns  the  apparent  location  of  the  target 

‘zh’  Returns  the  z-value  at  the  top  in  the  target 
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^z.Bin,  z.naz.  z.min,  z.maz’ 

Returns  the  extents  of  the  target  (In  viewer  coordinates) 

‘proj’  Returns  an  orientation  matrix  for  the  target’s  projection  coordinate  system.  In  this 
coordinate  system,  Y  runs  down  the  line  of  sight,  Z  runns  perpendicular  to  Y  and  the 
world  XY  plane,  and  X  runs  perpendicular  to  Y  and  Z. 

‘dist’  Returns  the  distance  to  the  origin  of  the  target’s  coordinate  system 
‘objact.corraction’ 

Returns  the  ratio:  distance  to  the  nearest  point  on  the  target  divided  by  the  distance 
to  the  target 

‘raster’  Returns  a  rasterized  outline  of  the  target 

ctdb^pparent..shape  is  similar  to  ctdb^pparentjiize,  except  that,  in  addition  to  returning  the 
"size"  of  the  distant  object,  it  returns  the  raster  ^ving  a  bitmap  of  the  outline  of  the  vehicle  as 
seen  from  the  eye  point.  In  addition,  it  returns  the  apparent  leftmost,  rightmost,  top  and  bottom 
of  the  object  in  "projection"  coordinates.  This  is  the  frame  of  reference  for  the  raster. 

The  value  of  object. correction  returned  is  used  by  the  caller  to  pass  to  subsequent  r^llR  to 
ctdb.ptop.raster.  This  value  is  a  ratio,  the  distance  from  the  viewpoint  to  the  nearest  vertex  of 
the  target  divided  by  the  distance  to  the  target. 

The  value  of  zh  returned  is  the  z-coordinate  of  the  highest  vertex  of  the  target  as  as  seen  from 
the  viewer’s  perspective,  expressed  in  world  coordinates. 

See  Section  3.2  [ctdb'apparent'size],  page  16. 


3.2  ctdb-apparent-size 


void  ctdb.apparant.sizafzO.  jO.  zO.  zl,  yl,  zl, 

rotation,  length,  width,  height, 
app.loc,  app.eidth,  ^p.height) 


float64 

xO,  yO,  zO; 

float64 

zl,  yl,  zl; 

float64 

rotation [3] [3] ; 

float64 

length,  width,  height; 

float64 

app.loc [3] ; 

float64 

eapp.width; 

float64 

eapp.beight; 

‘xO,  yO,  zO’ 
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Specifies  the  location  of  the  viewer 
‘xl,  yl.  zl’ 

Specifies  the  location  of  the  target 

‘rotation’ 

Specifies  the  3x3  rotation  matrix  of  the  target 
‘length’  Specifies  the  length  of  the  target  (its  Y  dimension) 

‘width’  Specifies  the  width  of  the  target  (its  X  dimension) 

‘height’  Specifies  the  height  of  the  target  (its  Z  dimension) 

‘app.loc’  Returns  the  apparent  location  of  the  target 

‘app.width.  app.height’ 

Returns  the  apparent  dimensions  of  the  target 

ctdb^pparent^ize  finds  the  apparent  size  of  the  perpendicular  parallelepiped  described  by 
length,  width,  height,  given  the  eye  point  xO,yO,zO,  the  target  location  xl,yl,zl  and  target  ro¬ 
tation.  The  apparent  width  and  height  of  the  object  are  returned,  as  well  as  a  location  corrected 
to  be  at  the  bottom  center  of  the  apparent  location. 

This  function  is  provided  to  allow  extremely  accurate  intervisibility  tests.  Ideally  this  should  be 
run  for  the  target,  as  well  as  for  each  potentially  blocking  vehicle.  For  applications  needing  a  more 
coarse  measure  of  visibility,  it  is  probably  not  necessary  to  use  this  function. 

See  Section  3.1  [ctdbapparent  shape],  page  15. 


3.3  ctdb-contour-image 


void  ctdb.contour.imageCctdb, 

low.z,  low.y,  width,  height, 
scale.mpp, 

dirt .pixel ,  contour .pixel , 
img) 


CTDB 

*ctdb: 

int32 

low.x; 

int32 

low.y; 

int32 

width; 

int32 

height ; 

float64 

8cal«.iBpp; 

int32 

dirt.pixel ; 

int32 

contour.pixel ; 

char 

iagD: 
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‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘lov.z,  lov.y,  width,  height’ 

Specifies  screen  extents,  in  meters. 

’8cale.Dpp’ 

Specifies  screen  scale  in  meters  per  pixel. 

’dirt.pizel,  contour.pizel’ 

Specifies  pixel  values  to  use  for  background  and  contours,  respectively, 
‘iog’  Returns  Z-pixmap  format  image  of  terrain  contours. 


ctdb^ontourJmage  generates  a  Z-pixmap  format  image  of  the  contours  of  the  terrain  bound  by 
lowoc4ow_y  to  low_X'»width,low.y<»height,  using  dirt^tixel  as  a  background,  and  contour_pixel  as 
the  foreground.  The  size  of  the  image  is  computed  from  scale.jnpp  (meters  per  pixel).  This  routine 
may  be  faster  than  ctdb-contourjsegments  for  extremely  large  terrain  areas,  although  its  use  at 
application  side  is  much  more  complicated. 

See  Section  3.5  [ctdb'contour 'segments],  page  19. 


3.4  ctdb.contour^oute 


void  ctdb^contour_rout«(ctdb,  zO,  yO,  zl,  yl, 

naz.dwviation,  dirwction, 
8in_8ignificant_slop«,  n.route,  routs) 

CTDB  *ctdb ; 

floated  zO,  yO; 

floated  zl,  yl; 

floated  aaz.daviation; 

int32  diraction; 

floated  8in.8ignif leant. alop«; 

int32  *n.rout8 ; 

R0UTE.P0IHT  routs  □; 


‘ctdb’  Pdnter  to  initialized  CTDB  structure. 

‘zO,  yO’  Specifies  start  of  route. 

‘zl,  yl’  Specifies  end  of  route. 

‘naz.dsviation’ 

Specifies  the  maximum  deviation  from  the  original  route 

‘direction’ 

Specifies  whether  valleys  or  crests  are  desired 
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‘sin.signilicant.slope’ 

Specifies  the  sin  of  the  minimum  slope  angle  which  should  be  considered  significant 
‘n_route’  Specifies  size  of  route  array.  Returns  number  of  points  in  route. 

‘route’  Returns  the  contoured  route. 

ctdb.contour.route  generates  a  route  between  points  zO.yO  and  xl.yl  which  follows  the 
contour  of  the  terrain.  The  route  either  attempts  to  stay  high  (direction«>CTDB_CR£ST)  or  low 
(direction»CTDB.VALLEY),  but  will  not  deviate  more  than  maz.deviation  from  the  original 
route.  The  route  is  returned  in  route  □  and  the  length  of  the  route  is  returned  in  n_route.  Upon 
invokation,  n_route  should  contain  the  maximum  number  of  points  which  will  fit  in  route.  When 
the  routine  returns,  routeCO]  will  be  at  zO.yO,  and  route[(*n_route)-i]  will  be  at  zl.yl. 

See  Section  3.23  [ctdb'profile' vector],  page  32. 


3.5  ctdb-contour_segments 


void  ctdb.contour_8egments(ctdb, 

interval, 

z.lov,  y.lov,  z.high,  y.high, 
drav.fcn) 

CTDB  ectdb; 
float64  interval; 

int32  z.lov,  y.lov,  z_high,  y_high; 
void  (edrav.f cn) (/*  int32  8eg.cnt; 

float64  8eg8[CTDB_NAX_C0NT0UR_PTS]; 
float64  elev8[CTDB.MAX_C0HT0UR.PTS/4] 
*/); 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘interval* 

Specifies  distance  between  contour  lines,  in  meters. 

‘z.lov,  y.lov,  z.high,  y.high’ 

Specifies  screen  extents,  in  meters. 

‘drav.fcn’ 

Called  periodically  to  draw  a  group  of  line  segments. 


ctdb  jcontour.segments  calls  the  passed  draw  Jen  for  each  contour  line  segment  in  the  area  bound 
by  xJow,yJow  to  xJugh,yJugh  at  the  specified  interval,  segxnt  is  the  number  of  elements  in  the 
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segsQ  array  (xO,  yO,  xl,  yl,  in  meters),  seg.cnt/4  is  the  the  number  of  elements  in  the  elevs[]  array 
(one  elevation  for  each  line  segment  in  the  segsQ  array). 


See  Section  3.3  [ctdb'contour 'image],  page  17. 


3.6  ctdb-find-ground_intersection 


int32  ctdb_find.ground_intar8«ction(ctdb,  xO,  yO,  zO,  zl,  yl,  zl, 

pt.rat,  tests, 
n.veh, 

veh,  ignoreO,  ignorel,  hit.veh) 


CTDB 

float64 

float64 

float64 

uint32 

int32 

CTDB.VEHICLE.LOCATIOH 

int32 

int32 


*ctdb; 
xO,  yO,  zO; 
xl,  yl,  zl; 
pt_ret[3] ; 

tests; 

n.veh; 

vehQ; 

ignoreO,  ignorel; 
*hit_veh; 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘xO,  yO,  zO’ 

Specifies  the  start  of  a  3D  line 
‘xl,  yl,  zl’ 

Specifies  the  end  of  a  3D  line 

‘pt.ret’  Returns  the  first  intersection  of  3D  line  with  ground  polygon 
‘tests’  Specifies  the  intersection  tests  to  be  performed 
‘n_veh’  Specifies  the  number  of  vehicles  in  the  vehQ  array. 

‘veh’  Specifies  locations  of  other  vehicles  which  may  block  visibility. 

‘ignoreO,  ignorel’ 

Specifies  0,  1,  or  2  vehicles  in  the  vehQ  array  which  should  not  be  checked, 
‘hit.veh’  Returns  the  first  vehicle  which  blocked  the  ray. 


ctdbJin(LgroundJntersection  locates  the  point  at  which  the  ray  from  <x0  yO  z0>  to  <xl  yl 
zl>  crosses  through  the  terrain  grid,  a  microterrain  polygon,  a  building,  or  a  tree  line  (including 
those  which  surround  canopies).  The  point  of  intersection  {*/-  1  meter  along  the  ray  when  testing 
ground  polygons)  is  returned  in  pt.jet.  If  no  such  intersection  can  be  found,  the  routine  returns  0, 
otherwise  one  of  the  following  constants: 
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CTDB.HIT.GROUHD 

Indicates  a  ground  polygon  was  intersected. 

CTDB.HIT.BUILDIMG 

Indicates  the  ray  passed  under  the  roofline  of  a  building. 

CTDB.HIT.TREELIHE 

Indicates  the  ray  passed  through  a  treeline,  or  under  the  edge  of  a  tree  canopy. 
CTDB.HIT.VEHICLE 

Indicates  the  ray  crossed  a  vehicle  in  the  veh  array. 

CTDB.HIT_WATER 

Indicates  the  ray  crossed  a  linear  feature  which  isn't  a  road. 

The  endpoints  are  clipped  to  database  boundarie  If  the  return  value  is  CTDB.HIT. VEHICLE, 
the  index  of  that  vehicle  in  the  veh  array  is  returned  in  *hit_veh.  Note  that  individual  trees  are 
not  modeled  accurately  enough  for  tests  of  them  to  be  meaningful. 

The  testa  parameter  should  be  an  inclusive  OR  of  the  same  constants  which  are  returned 
(CTDB.HIT.GROUND,  etc.).  Depending  upon  which  of  these  bits  are  set,  the  various  types  of  features 
will  be  tested  for  intersection  with  the  ray. 


3.7  ctdb-get-treeline_segment 


void  ctdb.g«t.tr«elina.segBant(ctdb.  ptO,  ptl) 
CTDB  ♦ctdb ; 

floated  ptOC2] ; 
floated  ptl  [2]; 


*ctdb’  Pointer  to  initialized  CTDB  structure. 

‘ptO,  ptl’  Return  the  endpoints  of  the  intersected  treeline  segment. 


ctdb^et.treelinejBegment()  must  be  called  *after*  a  call  to  ctdbJincLgioundintersection().  If 
a  treeline  was  intersected  in  the  call  to  rtdbJind^oundJntersection(),  then  the  endpoints  of  that 
segment  of  the  treeline  (in  meters  from  the  lower  left  coner  of  the  database)  are  returned  in  ptOQ 
and  ptlQ.  If  there  was  no  treeline  intersection  in  the  last  call  to  ctdbJind^oundJntersection(), 
zeros  are  returned  in  ptOQ  and  |*t  I H. 


3.8  ctdb JfindJiigh-ground 
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float64  ctdb_flnd_high_ground(ctdb,  xO,  yO,  zi,  yl.  zy.at.high) 
CTDB  *ctdb; 
float64  zO,  yO; 
float64  zl,  yl; 
float64  *zy_at_high: 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘zO,  yO’  Specifies  the  start  of  the  search  line 
‘zl,  yl’  Specifies  the  end  of  the  search  line 
‘zy_at_high’ 

Returns  the  X  and  Y  coordinates  of  the  high  point  (applications  may  pass  NULL,  if 
they  are  not  interested  in  this  value). 


ctdbJindJiigh^ound  returns  the  elevation  of  the  highest  point  between  xO,yO  and  xl  jl.  If 
non-NULL,  xy^t  Jiigh  will  be  filled  in  with  the  x  and  y  values  of  this  point.  Hence,  to  get  the  3D 
point,  usage  would  be:  vec[Z]  =  ctdbJindJiigh^ound(ctdbpcO,yO,xl jrl,vec);  The  ray  from  xO,yO 
to  xl,yl  is  clipped  to  terrain  boundaries,  if  the  ray  does  not  cross  the  terrain,  the  returned  elevation 
will  be  0.0,  and  the  returned  point  will  by  x0,y0. 


3.9  ctdb_hyp8o Jiitmap 


void  ctdb.hypso.bitmapCctdb,  lov.z,  lov.y,  width,  height, 

8cale.iq)p,  min.z,  Baz_z,  bitmap) 


CTDB 

*ctdb ; 

int32 

lov.z; 

int32 

lov.y; 

int32 

vidth; 

int32 

height ; 

float64 

>cale.Bipp; 

float64 

■lzi.z; 

float64 

Baz.z; 

char 

bitaiapD ; 

‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘lov.z,  lov.y,  vidth,  height’ 

Specifies  screen  extents,  in  meters. 

‘8cale.iflpp’ 

Specifies  screen  scale  in  meters  per  pixel. 
‘ain_z,  maz.z’ 
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Specifies  the  minimum  and  maximum  altitudes  which  should  be  represented  (ctdb- 
>min_z  and  ctdb->maxjE  are  good  candidates). 

‘bitmap’  Returns  an  XY-bitmap  format  image  of  the  hypsometric  map. 

ctdb-hypso.bitmap  generates  an  XY-bitmap  format  hypsometric  image  of  the  terrain  bound  by 
low_x4ow_y  to  low^-*^width4ow.y-*^height,  using  dithering.  Points  off  the  terrain  database  are  set 
to  0.  The  size  of  the  image  is  computed  from  scale_mpp  (meters  per  pixel).  min_z  and  maxj  are 
passed  in  by  the  caller,  points  at  or  below  min^  use  an  empty  dither,  and  points  at  or  above  max j 
use  a  solid  dither.  Points  in  between  use  dither  patterns  with  density  proportional  to  elevation. 
The  returned  bitmap  is  suitable  for  a  call  to  ZPutlsmgaO  or  XCraataPixmapFromBitmapDataO. 

NOTE:  This  function  is  conditionally  compiled  only  if  the  the  CFLAGS  has  -DHYPSO.  This 
avoids  a  dependency  on  libdither  if  libctdb  is  not  being  used  for  hypsometric  map  drawing. 


3.10  ctdb Jiypso_image 


‘ctdb’ 


void  ctdb.hypso.imagaCctdb,  lov.z,  lov.y.  vidth,  height, 

scale.mpp , 

ncells,  cmap,  of f .terrain.pixel , 
img,  min.z,  max.z) 


CTDB 

*ctdb ; 

int32 

lov.z; 

int32 

lov.y; 

int32 

vidth; 

int32 

height; 

float64 

scale.app; 

int32 

ncells ; 

int32 

cmapO; 

int32 

off.terrain.pizel 

char 

iagD: 

float64 

*ain.z; 

floated 

*aaz.z; 

Pointer 

to  initialized  CTDB  structure. 

‘lov.z,  lov.y,  vidth,  height’ 

Specifies  screen  extents,  in  meters. 

‘scale.^p’ 

Specifies  screen  scale  in  meters  per  pixd. 

‘ncells’  Specifies  the  number  of  cells  available  in  the  color  map. 
‘cmap’  Specifies  pixel  values  for  elevation  ranges. 
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‘off_t«rrain_pizel’ 

Specifies  pixel  value  for  points  off  the  terrain  database. 

‘lag’  Returns  a  Z-pixmap  format  image  of  the  hypsometric  map. 

Hain  z,  aax.z' 

Returns  the  minimum  and  maximum  altitudes  in  the  area  (useful  for  assigning  colors 
to  the  colormap). 

ctdbJiypsoJmage  generates  a  Z-pixmap  format  hypsometric  image  of  the  terrain  bound  by 
low_x4ow_y  to  low_X'*'width4ow_y-»height,  using  the  pixel  values  specified  in  the  cmap[0..ncells- 
1]  array.  Points  off  the  terrain  database  are  set  to  the  off^errain.pixel  value.  The  size  of  the 
image  is  computed  from  scalejtnpp  (meters  per  pixel).  *minjE  and  *max^  return  the  elevations 
corresponding  to  cmap[0]  and  cmap[ncells-l],  respectively.  It  is  expected  that  the  caller  can  use 
this  information  to  change  the  color  map  appropriately. 

NOTE:  This  function  is  conditionally  compiled  only  if  the  the  CFLAGS  has  -DHYPSO.  This 
avoids  a  dependency  on  lib  dither  if  libctdb  is  not  being  used  for  hypsometric  map  drawing. 


3.11  ctdb  Jookup.jelevation 

float64  ctdb.lookup.elevationCctdb,  x,  y) 

CTDB  *ctdb; 
floated  z; 
floated  y; 

‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘z,  y’  Specifies  a  point  on  the  database. 

ctdbJookupjdevation  finds  the  elevation  at  the  specified  point  on  the  terrain  database  based 
upon  the  elevation  grid  and  microterrain,  x  and  y  are  in  meters.  The  point  is  tested  to  make  sure 
it  is  not  off  the  terrmn  database  (it  is  not  necessary  for  the  application  to  make  this  check),  and 
0.0  is  returned  in  that  case. 

See  Section  3.13  [ctdb ‘lookup 'max'elevation],  p^  25. 


3.12  ctdb Jookup_feature Jnfo 
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int32  etdb.lookup_fenture.info(ctdb.  z,  y, 

■oil.ret.  vidth.ret,  direct ion.ret) 

CTDB  ectdb; 

floated  z ; 

floated  y: 

int32  *aoil_ret ; 

floated  *«idth_ret; 

floated  direction.rat [2] ; 

‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘z,  y’  Specifies  a  point  on  the  database. 

‘aoil.ret’ 

Returns  the  s(m1  type  of  the  feature 

‘width.ret’ 

Returns  the  width  of  the  feature 
^direct  ion_ret  ’ 

Returns  the  direction  of  the  feature 


ctdbJookupJeatureJnfo  takes  a  point  and  looks  to  see  if  there  is  a  linear  feature  under  it.  If 
so  it  returns  1  and  fills  in  the  the  type,  width,  and  direction  variables  passed  to  it.  Otherwise  it 
returns  0  and  type,  width,  and  direction  are  undefined. 


3.13  ctdb Jookup_xnax_elevation 

floatdd  ctdb.lookupjuz.eleyat ion (ctdb,  z,  y,  check.canopies) 

CTDB  *ctdb; 
floated  z; 
floated  y; 

int32  check_canopies; 

‘ctdb’  Painter  to  initialized  CTDB  structure. 

‘z,  y’  Specifies  a  point  on  the  database. 

‘check.canopies’ 

Indicates  whether  the  altitude  returned  should  clear  tree  canopies. 

ctdbJookupjnaxjelevation  finds  the  elevation  at  the  specified  point  on  the  terrain  database 
based  upon  the  elevation  grid,  microterrain,  buildings,  and  if  checkjcanopies  is  ‘TRUE’,  tree  canopies. 
X  and  y  are  in  meters.  The  point  is  tested  to  make  sure  it  is  not  off  the  terrain  database  (it  is  not 
necessary  for  the  application  to  make  this  check),  and  0.0  is  returned  in  that  case. 
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3.14  ctdb Jookup_soil 


int32  ctdb.lookup.soiKctdb,  x,  j) 
CTDB  *ctdb; 
float64  x; 
float64  y: 


‘ctdb’  Pointer  to  initialized  CTDB  structure, 
‘x,  y’  Specifies  a  point  on  the  database. 


ctdbJookupjK>il  finds  the  soil  type  at  the  specified  point  on  the  terrain  database  based  upon 
the  elevation  grid  and  microterrain.  x  and  y  are  in  meters.  The  point  is  tested  to  make  sure  it  is 
not  off  the  terrain  database  (it  is  not  necessary  for  the  application  to  make  this  check),  and  0  is 
returned  in  that  case. 


3.15  ctdb_place.vehicle 


void  ctdb.place.v«hicl«(ctdb,  z.  j,  length,  vidth,  dx,  dy, 

z,  rotation,  soil) 

CTDB  «ctdb ; 

float64  x; 
floated  y: 
floated  length; 
floated  vidth; 
floated  dx; 
floated  dy; 
floated  *z; 

floated  rotation [3] C3] ; 

int32  *soil ; 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘x,  y’  Specifies  a  point  on  the  database. 

‘length,  vidth’ 

Specifies  the  length  (Y  dimension)  and  width  (X  dimension)  of  the  vehicle. 

‘dx,  dy’  Specifies  the  direction  of  the  vehicle  as  a  cosine/sine  pair,  north  =  <0  1>,  south  =  <0 
•1>,  east  =  <1  0>,  =  <  1  0> 

‘z’  Rntums  the  elevation  at  the  point. 

‘rotation’ 

Returns  a  3x3  rotation  matrix  for  the  vehicle. 
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‘soil’  Returns  the  soil  type  at  the  point. 

ctdb4>lace.vehicle  finds  the  elevation,  hull-to-world  rotation  matrix,  and  soil  type  for  a  vehicle 
siting  at  the  specified  point,  facing  the  specified  direction,  x,  y,  length,  and  width  are  in  meters. 
<dx  dy>  is  assumed  to  be  a  unit  vector  pointing  in  the  direction  of  the  vehicle.  The  elevation  is 
returned  in  *z,  the  rotation  matrix  is  filled  in,  and  the  soil  type  is  returned  in  ^soil.  The  point  is 
tested  to  make  sure  it  is  not  off  the  terrain  database  (it  is  not  necessary  for  the  application  to  make 
this  check);  points  off  the  database  have  an  elevation  of  0.0,  a  flat  rotation  matrix  pointing  in  the 
specified  direction,  and  a  soil  type  of  0. 


3.16  ctdb_pointuon^atabase 

int32  ctdb_point_on_databasa(ctdb,  x.  y) 

CTDB  *ctdb: 
float64  x; 
floated  y; 

‘ctdb*  Pointer  to  initialized  CTDB  structure. 

*z,  y’  Specifies  the  point  to  check. 

ctdb-pointjonjdatabase  returns  1  if  the  point  is  on  the  database,  0  if  it  is  not.  All  libctdb 
functions  make  this  check  internally. 


3.17  ctdb^oint_on_ground 


int32  ctdb.point.on.ground(ctdb,  x,  y,  radius,  soil.ret) 
CTDB  *ctdb ; 

floated  x; 
floated  y; 
floated  radius; 
int32  *soil_rst ; 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘x,  y’  Specifies  the  center  of  the  circle. 

‘radius’  Specifies  the  radius  of  the  circle. 

‘soil.ret’ 

Returns  the  soil  type  at  the  center  of  the  circle. 
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ctdb_pointa)n.ground  returns  1  if  the  circle  centered  at  the  passed  location,  with  the  specified 
radius  is  completely  ground  (no  trees  or  buildings  cross  the  circle).  The  soil  type  at  the  passed 
point  is  also  returned  so  the  caller  can  check  for  undesired  soil  types.  This  function  is  used  for 
initializing  vehicles  in  reasonable  locations. 

See  Section  3.15  [ctdb  place’ vehicle],  page  26. 


3.18  ctdb^et-buildings 

int32  ctdb_g«t_buildinga(ctdb,  x,  y,  radius,  maz.count,  buildings) 

CTDB  *ctdb ; 

floated  X ; 

f loat64  y : 

floated  radius ; 

int32  maz.count ; 

CTDB.FEATURE_OUTLINE  buildings  □; 

‘ctdb’  Pointer  to  initialized  CTDB  structure. 

*x,  y’  Specifies  the  center  of  the  circle. 

‘radius’  Specifies  the  radius  of  the  circle. 

‘maz.coxmt’ 

Specifies  the  maximum  number  of  buildings  to  count 

‘buildings’ 

If  non-NULL,  returns  list  of  building  outlines 

ctdb.g«t.buildings  returns  the  number  of  buildings  within  the  specified  radius  of  the  passed 
point.  If  any  comer  of  a  building  is  within  the  radius,  the  building  will  be  included  (note  that 
if  the  circle  faUs  completely  within  a  building,  that  building  will  not  be  detected).  If  non-NULL, 
buildings  will  be  filled  with  the  list  of  buildings  (where  maz.count  spedfies  the  number  which 
will  fit  in  the  passed  array).  The  maz.count  parameter  can  also  be  used  when  buildings  is  NULL 
to  indicate  the  maximum  number  to  count.  For  example,  if  the  question  being  asked  is  "are  there 
more  than  10  buildings  in  this  area?",  then  the  number  11  may  be  passed  in,  so  that  the  search 
can  be  stopped  as  soon  as  possible. 

The  buildings  are  returned  using  the  following  structure: 

typedef  struct  ctdb.feature.outlins 

< 


int32  n.verts ; 


Chapter  3:  Functions 


29 


float64  verts [10] [3] : 

}  CTDB.FEATURE.OUTLIME; 

n.verts  returns  the  number  of  vertices  in  the  outline  of  the  building,  and  verts  returns  the  3D 
coordinate  of  each  vertex  (following  the  roofline  of  the  building). 


3.19  ctdb.^oint-thru_point 

float64  ctdb.point.thru_point(ctdb.  zO,  yO,  zO,  zl,  yl,  zl,  zh, 

width,  tree.opacity, 
mlniaun. visibility,  range, 
n.veh, 

veh,  ignoreO,  ignorel) 

CTDB  vctdb ; 

float64  zO,  yO,  zO; 

float64  zl,  yl,  zl,  zh; 

float64  width; 

floated  tree.opacity; 

floated  minisnuB.  visibility; 

floated  range; 

int32  n.veh; 

CTDB.VEHICLE.LOCATION  vehQ; 

int32  ignoreO,  ignorel; 

‘ctdb’  Pdnter  to  initialized  CTDB  structure. 

‘zO,  yO,  zO’ 

Specifies  the  eye  pmnt. 

‘zl,  yl,  zl,  zh’ 

Specifies  the  target  location,  and  the  bottom  and  top  of  the  target. 

‘width’  Specifies  target  width. 

‘tree.opacity’ 

Specifies  redaction  of  visibility  resulting  from  trees. 

‘miniauB.  visibility’ 

Specifies  a  threshold  below  which  0  may  be  returned. 

‘range’  Specifies  the  range  of  the  radar  sensitive  to  clatter. 

‘n.veh’  Specifies  the  number  of  vehicles  in  the  vehQ  array. 

‘veh’  Specifies  locations  of  other  vehicles  which  may  block  visibility. 

‘ignoreO,  ignorel’ 

Specifies  0,  1,  or  2  vehicles  in  the  vehQ  array  which  should  not  be  checked. 
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ctdb.point.thrtt^oint  is  a  special  version  of  intervisibility  for  use  with  radar.  Within  the  passed 
range,  objects  behind  the  target  block  visibility  to  the  same  extent  as  objects  in  front  of  it. 

See  Section  3.20  [ctdb'point'to' point],  page  30. 

See  Section  3.24  [ctdb'ptop'raster],  page  32. 

See  Section  3.27  [ctdb'vehicle'blockage],  page  35. 

See  Section  3.2  [ctdb'apparent'size],  page  16. 


3.20  ctdb-point_to^oint 


float64  ctdb_point_to_point(ctdb.  zO.  yO,  zO,  zl,  yl,  zl,  zb, 

Bidth,  traa.opacity , 
miniauB. visibility,  n.vah, 
v«h,  ignoreO,  ignoral) 

*ctdb : 
zO,  yO,  zO; 
zl,  yl,  zl,  zb; 
width; 

tree.opacity: 
minimua. visibility ; 
n_vsb; 
vshO ; 

ignorsO,  ignorsl; 


CTDB 

floated 

floated 

floated 

floated 

floated 

iiit32 

CTDB.VEHICLE.LOCATIOM 

iut32 


‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘zO,  yO,  zO’ 

Specifies  the  eye  point. 

‘zl,  yl,  zl,  zb’ 

Specifies  the  target  location,  and  the  bottom  and  top  of  the  target. 

‘width’  Specifies  target  width. 

‘troa.opacity’ 

Specifies  reduction  of  visibility  resulting  from  trees. 

‘niniauB.  visibility’ 

Specifies  a  threshold  below  which  0  may  be  returned. 

‘n_vah’  Specifies  the  number  of  vehicles  in  the  vehQ  array. 

‘vah’  Specifies  locations  of  other  vehicles  which  may  block  visibility. 

‘ignoraO,  ignoral’ 

Specifies  0,  1,  or  2  vehicles  in  the  vehQ  array  which  should  not  be  checked. 
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ctdb4)oint.to^oint  performs  an  intervisibility  check  starting  at  the  point  xO,yO  and  proceeding 
to  the  point  xl^l.  zO  is  the  eye  point  of  the  viewer  and  zl  and  zh  are  the  bottom  and  top  of  the 
target,  width  is  the  width  of  the  target,  and  is  used  when  comparing  against  individual  trees  and 
buildings,  otherwise  a  zero-width  target  is  assumed.  All  these  values  are  in  meters,  treejopacity 
encapsulates  the  effect  trees  have  on  the  visual  sysiem  being  modeled.  An  opacity  of  0  indicates  trees 
have  no  effect;  1  indicates  trees  completely  block  visibility.  The  effect  of  multiple  trees  is  combined 
using  a  simple  light  transmittance  model.  The  visible  target  area  (adjusted  for  tree  opacity)  is 
returned  as  a  floating  point  number  in  the  range  0.0  to  1.0  (0.0  for  complete  blockage,  1.0  for 
complete  visibility).  Since  visibility  can  only  get  smaller  as  more  features  are  tested,  knowing  the 
minimum  visibility  interesting  to  the  application  can  greatly  enhance  the  speed  of  calculation.  Even 
very  small  values  (such  as  0.05)  can  greatly  increase  speed.  If  the  visibility  measure  drops  below 
this  visibility,  0.0  will  be  returned.  The  ray  from  x0,y0  to  xl,yl  is  clipped  to  terrain  boundaries, 
visibility  is  1.0  in  areas  off  the  terrain  database. 


The  last  set  of  parameters  are  only  examined  if  n.veh  is  non-zero;  hence  they  need  not  be 
passed  unless  vehicle  blocking  vehicle  intervisibility  calculations  are  required.  If  n.veh  is  non-zero, 
ctdb^oint_to4>oint  first  calls  ctdb.vehicle_blockage  with  the  arguments  specified  (see  Section  3.27 
[ctdb'vehicle'blockage],  page  35,  for  an  explanation  of  these  arguments).  Note  that  since  a  target 
could  be  partially  blocked  by  terrain  and  partially  blocked  by  vehicles,  two  separate  calls  (one  to 
ctdb^)oint.to.point  with  n_veh=0,  and  one  to  ctdb_vei:ucle.biockage)  will  not  necessarily  yield  the 
same  result  as  one  call  to  ctdb^oint.to.point  with  n.veh>0. 


See  Section  3.19  [ctdb'point'thru'point],  page  29. 
See  Section  3.27  [ctdb'vehicle'blockage],  page  35. 
See  Section  3.24  [ctdb'ptop'raster],  page  32. 

See  Section  3.2  [ctdb'apparent'size],  page  16. 


3.21  ctdb-print_description 

void  ctdb_print_de8criptioo(ctdb) 

CTDB  *ctdb; 

‘ctdb’  Pointer  to  initialized  ('11)11  structure. 

ctdb.j)rint_description  prints  a  description  of  the  passed  ctdb  database  including  min/max  in¬ 
formation  and  memory  usage  statistics. 
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3.22  ctdb^rint^tats 

void  ctdb.print.statsCctdb) 

CTDB  *ctdb; 

‘ctdb’  Pointer  to  initialized  CTDB  structure- 
ctdb^rint^tats  prints  cache  performance  statistics. 


3.23  ctdb^rofile-vector 

int32  ctdb .profile. vector (ctdb,  xO,  yO,  xl,  yl,  n.prof,  prof) 

CTDB  ectdb; 
floated  xO,  yO; 
floated  xl.  yl; 
int32  en.prof ; 
floated  prof  □  [3] ; 

‘ctdb’  Pointer  to  initialized  CTDB  structure. 

‘xO ,  yO’  Specifies  start  of  vector. 

‘xl,  yl’  Specifies  end  of  vector. 

‘n.prof  ’  Specifies  size  of  prof  array.  Returns  number  of  point  in  profile. 

‘prof’  Returns  exact  3D  profile  of  vector,  conforming  to  each  grid  or  microterrain  edge. 

ctdb^rofile_vector  generates  a  sequence  of  3D  points  along  the  specified  ray  from  xO,yO  to  xl,yl 
which  exactly  follow  the  contour  of  the  terrain.  The  points  are  returned  in  profQ  and  the  number 
of  points  is  returned  in  n^rof.  Upon  invocation,  n.prof  should  contain  the  maximum  number  of 
points  which  will  fit  in  profQ.  If  more  profile  points  are  necessary  than  will  fit  in  profQ,  the  function 
returns  0,  otherwise  it  returns  1.  ctdb^rofile.vector  clips  the  specified  ray  to  terrain  database 
boundaries,  hence  the  points  x0,y0  and  xl,yl  will  not  necessarily  be  the  first  and  last  points  in  the 
profQ  array  (although  they  usually  will  be). 


3.24  ctdb^top_raster 


floated  ctdb.ptop.rastarCctdb,  xO,  yO,  zO,  zl,  yl.  zl.  zh, 

uidth,  ftypo,  object .correction,  tree.opacity , 
minioum. visibility,  grid. 
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CTDB 

float64 

float64 

float64 

int32 

lloat64 

float64 

float64 

CTDB.RASTER 

float64 

float64 

float64 

float64 

float64 

int32 


T_min,  z.max.  z.iilin,  z.maz,  actual. visible.area, 
n.veh,  veh,  ignoreO,  ignorel) 

*ctdb; 
xO,  yO,  zO; 
xl,  yl,  zl,  zh; 
width; 
ftype; 

obj ect.correction; 
tree.opacity; 

Binifflun. visibility ; 
grid; 

«x_min; 

«x.Baz; 

«z.iain; 

vz.max; 

vactual.visible.area ; 
n.veh; 


CTDB.VEHICLE_LOCATION  vehD; 


int32 


ignoreO,  ignorel; 


^ctdb'  Pointer  to  initialized  CTDB  structure. 

‘xO,  yO,  zO’ 

Specifies  the  eye  point. 

‘xl,  yl,  zl,  Zh’ 

Specifies  the  target  location,  and  the  bottom  and  top  of  the  target. 

‘width’  Specifies  target  width. 

‘ftype’  If  viewing  a  feature,  specifies  the  type  of  feature  being  viewed. 

‘obj  ect . correct ion’ 

Specifies  target  scale  factor  (see  below). 

‘tree.opacity’ 

Specifies  reduction  of  visibility  resulting  from  trees. 

‘minimua.  visibility’ 

Spedfies  a  threshold  below  which  0  may  be  returned. 

‘grid’  Specifies  the  exact  profile  of  the  target. 

‘x_min,  z.maz,  z.ffiin,  z.b8z’ 

Specifies  the  size  of  the  target  in  various  dimensions. 

‘actual.visible.area’ 

Returns  actual  visible  area. 

‘n_v«h’  Specifies  the  number  of  vehicles  in  the  vehQ  array. 

‘v«h’  Specifies  locations  of  other  vehicles  which  may  block  visibility. 

‘ignoreO,  ignorel’ 

Specifies  0,  1,  or  2  vehicles  in  the  vehQ  array  which  should  not  be  checked. 
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ctdb^top_raster  is  the  same  as  ctdb.point_to_point  except  that  it  takes  an  additional  argument, 
CTDBJLA.STER  grid,  a  pre-computed  raster  supplied  by  the  client.  It  also  requires  the  frame 
of  reference  (x.jnin,  x-max,  zunin,  z-max)  in  "projection"  coordinates  of  the  raster.  These  are 
adjusted  according  to  the  result  of  the  intervis  computation  and  passed  back  to  the  caller  to 
reticulate  the  object. 

Object  correction  must  be  supplied  by  the  caller  and  is  computed  by  a  call  to 
ctdb.apparant.shapa.  This  value  is  used  as  a  scale  factor  to  "pull  back"  the  shape  of  the  target 
along  parametric  lines  to  the  eye  point  to  enable  intervis  calculations  in  two  steps  for  terrain  features 
as  targets. 

See  Section  3.20  [ctdb'point'to'point],  page  30. 

See  Section  3.19  [ctdb'point'thru'point],  page  29. 

See  Section  3.27  [ctdb' vehicle' blockage],  page  35. 

See  Section  3.2  [ctdb'apparent'size],  page  16. 

See  Section  3.1  [ctdb'apparent'shape],  page  15. 


3.25  ctdb_read 

void  ctdb.readffnaflte,  ctdb,  mefflory.lisit) 
char  vfnana; 

CTDB  *ctdb ; 

lnt32  mefflory.limit; 

‘fname’  File  name  of  database.  Can  be  any  valid  unix  path  in  the  style  of  open(2}. 

‘ctdb’  Pointer  to  uninitialized  ‘CTDB’  type  variable. 

‘memory.liiBit’ 

Maximum  amount  of  memory  which  should  be  used,  in  bytes. 

ctdb  jead  loads  the  ctdb  format  terrain  database  from  the  named  file,  and  puts  the  resulting 
information  into  the  user-supplied  CTDB  structure.  This  structure  will  be  needed  for  calls  to 
almost  all  libctdb  functions. 

If  the  database  needs  less  than  the  allowed  amount  of  memory,  only  the  amount  needed  will 
be  allocated.  If  the  database  is  larger  than  this  amount,  a  cache  will  be  used,  sized  to  fit  within 
this  limit.  Note  that  the  special  value  ‘0’  may  be  used  to  indicate  an  unlimited  amount  of  memory 
(usually  a  bad  idea,  since  the  libctdb  cache  will  typically  perform  much  better  than  virtual  memory 
would). 
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It  is  assumed  that  loading  databases  occurs  during  the  initialization  phase  of  a  program,  and 
hence  if  an  error  is  detected,  libctdb  will  invoke  exit(l). 


3.26  ctdbjreread 

void  ctdb.rereadCfnaffle,  ctdb,  mefflory.liait) 
char  *f  name ; 

CTDB  ecldb; 
int32  memory. 1  imit ; 

‘fname’  File  name  of  database.  Can  be  any  valid  unix  path  in  the  style  of  open(2). 

‘ctdb’  Pointer  to  initialized  ‘CTDB’  type  variable. 

‘memory.limit’ 

Maximum  amount  of  memory  which  should  be  used,  in  bytes. 

ctdb  jead  loads  the  ctdb  format  terrain  database  from  the  named  file,  and  puts  the  resulting 
information  into  the  user-supplied  CTDB  structure,  as  in  ctdb.read.  However,  it  is  assumed  that 
the  passed  CTDB  structure  already  contains  a  database,  and  that  the  memory  used  by  the  orifpnal 
database  must  be  either  reused  or  freed. 

See  Section  3.25  [ctdb'read],  page  34. 


3.27  ctdb-vehicle_blockage 


floated  ctdb.vehicle.blockageCctdb,  zO,  yO,  zO,  zl,  yl,  zl,  zh. 

vidth,  &_vah,  vah,  ignoreO,  ignoral) 
*ctdb ; 
zO,  yO,  zO; 
zl,  yl,  zl,  zh; 
vidth; 
n.vah; 
vahO ; 

ignoraO,  ignoral; 


CTDB 

floated 

floated 

floated 

int32 

CTDB.VEHICLE.LOCATIQN 

int32 


‘ctdb*  Pointer  to  initialized  CTDB  structure. 

‘zO,  yO,  zO’ 

Specifies  the  eye  point. 
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'zl,  yl.  zl,  zh’ 

Specifies  the  target  location,  and  the  bottom  and  top  of  the  target. 

‘vidth’  Specifies  target  width. 

‘n_veh’  Specifies  the  number  of  vehicles  in  the  vch[]  array. 

‘veh’  Specifies  locations  of  other  vehicles  which  may  block  visibility. 

‘ignoraO,  ignorel’ 

Specifies  0,  1,  or  2  vehicles  in  the  veh[]  array  which  should  not  be  checked. 

ctdb.vehicleJblockage  performs  a  visibility  check  from  the  eye  point  to  the  target  point,  com¬ 
paring  against  the  vehicles  passed  in  the  veh[]  array.  The  locations  and  width  are  as  in 
ctdb^oint_to.4>oint.  n.veh  is  the  size  of  the  vehQ  array.  Vehicles  in  the  vehQ  array  are  only  checked 
if  the  ’used’  field  is  set.  The  height  and  width  are  assumed  to  be  projected  onto  the  viewing  plane 
of  the  observer.  Two  vehicles  can  be  eliminated  from  the  search  by  setting  ignoreO  and  ignorel 
to  their  indices  in  the  vehQ  array.  To  avoid  eliminating  vehicles,  pass  CTDBJ)ONTJGNORE  for 
ignoreO  and  ignorel.  As  in  ctdb.point.to_point,  the  return  value  is  in  the  range  0.0  for  full  blockage, 
to  1.0  for  full  visibility. 

See  Section  3.2  [ctdb'apparent'size],  page  16. 

See  Section  3.20  [ctdb'point'to'point],  page  30. 
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4  P  o  rtin  g  G  u  id  e 


The  libctdb  library  has  been  compiled  on  the  following  platforms: 

•  Mips 

•  Apollo 

•  Hewlett-Packard 

The  code  is  written  to  be  extremely  portable,  but  on  other  platforms  some  modification  may  be 
necessary.  The  most  likely  problem  is  the  lack  of  the  single  precision  square  root  function  fsqrtO. 
The  first  definitions  in  the  header  file  ‘libctdb. h’  allow  correction  of  this  problem: 

•ifdef  apollo 
•define  fsqrt  sqrt 
•endif 


This  can  be  extended  to  correct  similar  problems  on  other  machines. 

Another  potential  problem  is  the  dependency  on  the  common  library  ‘libdithar*.  This  library  is 
only  used  if  the  hypsometric  map  generating  functions  ctdb_h3rp80.iaage  or  ctdb.h7pso.bitB^) 
will  be  used  on  the  target  platform.  If  these  functions  will  be  used,  the  preprocessor  symbol  HYPSO 
must  be  defined.  This  can  be  achieved  in  the  ‘Makefile’  with  the  line: 

EZTIU.CFUGS  -  -DHYPSO 


Omitting  the  HYPSO  definition  will  cause  the  hypsometric  mapping  functions  to  be  omitted  from 
the  ‘libctdb. a’  archive,  and  hence  the  common  include  file  ‘libdither.h’  will  not  be  needed. 


4.1  Platform  specific  optimization 

The  libctdb  source  code  has  been  written  in  a  manner  which  works  best  when  compiled  with  an 
optimizing  compiler.  For  almost  all  compilers,  optimization  is  enabled  with  the  compiler  flag  ‘-O’. 
This  should  be  one  of  the  arguments  passed  to  ‘cc’  when  this  library  is  compiled. 

Other  heuristics  have  been  applied  as  well  (see  Section  1.4  [Optimized  for  RISC],  page  7).  In 
general,  these  conventions  will  nc :  have  a  significant  impact  on  non-RISC  architectures.  If  porting 
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to  a  new  platform  on  which  performance  is  a  primary  concern,  the  use  of  a  profiler  is  highly 
encouraged,  ‘teat.c’  in  the  libctdb  library  is  good  test  program  for  use  with  a  profiler.  The 
mechanics  of  profiling  differ  from  platform  to  platform,  but  the  following  rules  should  generally 
apply: 

•  Always  profile  an  optimized  executable.  The  execution  profile  of  non-optimized  code  is  gener¬ 
ally  nothing  at  all  like  the  profile  of  optimized  code. 

•  Do  not  change  the  calling  sequences  of  functions  to  be  different  for  a  particular  platform.  This 
inhibits  portability  and  reuse  of  code. 

•  Never  make  a  change  to  the  code  without  testing  to  see  if  it  actually  improved  performance. 
The  ‘test’  program  can  be  used  to  confirm  average  execution  times  for  most  functions. 

•  If  a  change  is  specific  to  a  particular  platform,  it  should  be  coded  using  ‘tif  daf  ’  syntax.  For 
example,  if  a  target  platform  performs  significantly  better  using  unsigned  short  rather  than 
int  for  iteration  variables,  an  appropriate  coding  would  be: 

/*  Optimization  */ 

•ifdef  my_machine 

•define  ITERATOR.TYPE  uint32  short 

•else 

•define  ITERATOR.TYPE  int 
•endif 

ITERATOR.TYPE  i; 

•  •  • 

> 

This  allows  future  porters  to  easily  decide  whether  this  optimization  improves  performance  on 
their  target  platform. 
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1  O  verv  ie  w 


LibDelObj  provides  a  simple  object  deletion  editor  for  the  GUI.  The  user  can  select  objects  to 
delete  (which  are  marked  with  big  red  X’s),  then  can  delete  them  by  clicking  "Done".  The  library 
takes  care  of  some  of  the  complexities  of  deleting  object,  such  as  removing  text  associated  with 
deleted  objects. 
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Chapter  2:  Usage 
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2  Usage 


The  software  library  ‘libdelobj  .a’  should  be  built  and  installed  in  the  directory 
Vcoonion/lib/’.  You  will  also  need  the  header  file  "libdelobj  .h’  which  should  be  installed  in  the 
directory  Vconmon/include/libinc/'.  If  these  hies  are  not  installed,  you  need  to  do  a  ^aka'  in 
the  libdelobj  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libdelobj. 


2.1  Building  Libdelobj 

The  libdelobj  source  files  are  found  in  the  directory  Vcomon/libsrc/libdelobj’.  ‘RCS’  format 
versions  of  the  files  can  be  found  in  '/nfs/coaaon.src/libsrc/libdelobj’. 

If  the  directory  ‘cooimon/libsrc/libdelobj’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

i  cd  conmon/libsrc/libdelobj 
•  CO  RCS/*,v 
i  make  install 

This  should  compile  the  library  "libdelobj  .a’  and  install  it  and  the  header  file  ‘libdelobj  .h* 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libdelobj  should  compile 
without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libdelobj 

Libdelobj  can  be  linked  into  am  .iiipliration  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/common/lib  -Idelobj  [other  libraries] ’.  If  your  compiler  does  not  sup* 
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port  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/cooBon/lib/libdelobj  .a*. 

Libdelobj  depends  directly  on  the  following  libraries:  libsafgui,  libtactmap,  libcoordinates,  lib- 
sensitive,  libcallback,  libpo,  libeditor,  and  libreader. 


Chapter  3:  Functions 
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3  Functions 

The  following  sections  describe  each  function  provided  by  libdelobj,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  delobj-init 

void  delobj.initO 

delob j.init  initializes  libdelobj.  Call  the  before  any  other  libdelobj  function. 


3.2  delobj-init-gui 

int32  delobj_init.gui(data_path,  reader.f lags , 

gui,  tactnap,  tcc,  map.era8e.gc, 
sensitive,  ref resh.event ,  db) 
char  *data_path; 

uint32  reader .flags ; 

SGUI.PTR  gui; 

TACTMAP  _PTR  t  actmap ; 

COORD.TCC.PTR  tcc; 

GC  map_erase.gc; 

SNSTVE_VIin)OH.PTR  sensitive; 

CALLBACX_EVENT_PTR  ref resh.event ; 

Pa.DATABASE  *db; 

‘data_path’ 

Specifies  the  directory  where  data  files  are  expected 
‘reader.flags’ 

Specifies  flags  to  be  passed  to  reader  .read  when  reading  data  files 
‘gui’  Specifies  the  SAF  GUI 
‘tactmap’  Specifies  the  tactical  map 
‘tcc’  Specifies  the  map  coordinate  system 
‘map.erase.gc* 

Spedfies  the  GC  which  can  erase  things  from  the  tactical  map 

‘sensitive’ 

Specifies  the  sensitive  window  for  the  tactical  map 
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‘refresh. event’ 

Specifies  the  event  which  fires  when  the  map  is  refreshed 
‘db’  Specifies  the  persistent  object  database 

delob j.init.gui  create  the  object  deletion  tool.  The  data  file  ( ‘delob j  .rdr’)  is  read  either 
from  ‘.’or  the  specified  data  path,  depending  upon  the  reader.flags.  The  reader  .flags  are  as 
in  reader.read.  The  return  value  is  zero  if  the  read  succeeds,  or  one  of  the  libreader  return  values; 
READER.IIEAD.EIIROR,  READER.FILE.HOT.FOUND. 
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1  O  verv  ie  w 


Libdetonation  provides  a  model  of  proximity  detonation.  It  can  detect  detonations  due  to 
proximity  with  other  network  entities  (platforms,  missiles,  and  structures).  Proximity  detonation 
due  to  the  ground,  buildings,  and  other  terrain  features  is  not  yet  supported.  This  library  wiU 
generate  impact  PDUs,  if  told  to  do  so  for  a  given  vehicle. 

This  library  determines  that  a  detonation  should  occur  if  the  distance  to  the  target,  as  measured 
along  the  secant  between  positions  of  the  ticked  vehicle  (usually  a  missile)  during  consecutive  ticks 
achieves  a  local  minimum  (and  is  less  than  the  detonation.radius  parameter  specified  for  the 
model  instance.)  In  performing  this  calculation,  the  position  of  the  target  is  projected  forward  or 
backward  in  time  ("Anti-RVA")  to  find  the  point  on  its  trajectory  closest  to  the  point  where  the 
local  minimum  occurred.  This  estimated  location  is  passed  back  via  the  registered  DET.CALLBACK 
function.  If  the  local  minimum  has  been  passed  and  the  distance  to  the  target  is  greater  than 
detonation_radius,  then  a  near-miss  is  declared. 

There  are  two  models  used  for  selecting  potential  target  entities:  low-fidelity  and  high-fidelity. 
When  low-fidelity  detonation  is  used,  a  list  of  potential  targets  must  be  supplied  by  the  simulation. 
These  are  the  ONLY  vehicles  which  will  trigger  detonation.  When  high-fidelity  is  used,  libdetonate 
builds  a  suitable  list  of  nearby  vehicles  to  check.  This  is  considerably  more  expensive. 

In  addition  to  proximity  detonations  which  are  within  the  detonation  radius  specified  by  the 
parametric  data,  libdetonation  also  informs  clients  of  near-misses  with  vehicles  on  the  list  of  deto¬ 
nation  candidates. 

The  parameters  used  by  a  vehicle  (missile)  for  detonation  detection  are  specified  in  its  configu¬ 
ration  file  as  follows: 

(SM_Detonation  (check  {trees}  {buildings}  {ground} 

{platforms}  {aissiles}) 

(detonation.radius  <real  ■eters>) 

(fidelity  [highllos]) 


The  first  parameter,  check,  lists  those  things  for  which  detonation  detection  is  required.  This 
affects  performance  when  high-fidelity  detonation  is  enabled. 

The  detonation_radius  parameter  sperifios  the  maximum  proximity  which  will  trigger  a  det¬ 
onation  for  this  vehicle  (missile. ) 
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Finally,  the  fidelity  parameter  (which  has  a  value  of  high  or  lov)  is  used  to  determine 
the  method  for  selecting  potential  targets.  It  also  affects  the  expense  of  the  algorithms  used  in 
determining  if  detonation  should  occur. 

In  the  high  fidelity  model,  entire  classes  of  entities  are  checked  for  proximity,  while  in  the  low 
fidelity  model,  a  list  of  vehicles  (targets)  must  be  built  using  the  function  det_add.target(). 

det.tick  ticks  the  detonation  sub-class.  During  the  tick,  if  a  detonation  is  detected,  a  packet 
can  be  sent  and  the  callback  function  (if  any)  registered  with  det.class.init  will  be  invoked.  The 
detonation  tick  input  includes  the  vehicle  id  of  the  missile  and  a  pointer  to  the  terrain  database 
on  which  the  missile  is  simulated.  The  detonation  tick  processing  of  a  missile  includes  the  follow 
steps: 

1.  Set  the  libdetonation  variable,  old^os,  to  the  location  the  missile  was  at  last  tick  (detonation- 
>last4>os).  This  will  be  referred  to  as  old  position. 

2.  Get  libentity  information(ent_position,  ent.velocity,  ent^tationary)  and  store  it  as  new^ios, 
velocity,  and  stationary.  Set  the  detonation->last^os  field  to  new_pos  (the  newly  retrieved 
ent^osition). 

3.  Call  the  function  •nt.get.physdbCvehicle.id)  to  get  the  missile’s  physical  data,  which  in¬ 
cludes  the  missile  dimensions.  Find  an  upper  bound  size  by  using  the  maximum  of  length, 
width,  and  height.  This  upper  bound  is  needed  when  calculating  the  range  to  pass  to  the 
position  based  vehicle  table. 

4.  If  the  missile  is  stationary  it  is  not  necessary  to  check  for  detonations  with  terrain  so  omit 
DETJUILDINGS,  DET.GROUND,  and  DET.TREES  from  the  missUe’s  detect  checklist.  If 
the  detect  checklist  indicates  DET  J>LATFORMS,  DETJdlSSILES,  or  DET^UILDINGS  add 
the  relevant  types  (VTAB.VEHICLE,  VTAB-MISSILE,  VTAB-STRUCTURE)  to  the  missUe’s 
list  of  types-to-check. 

5.  If  the  missUe’s  detect  checklist  stUl  contains  some  types  and  high  fidelity  procesang  is  indicated 
for  this  missile,  create  a  binary  tree  vtab  structure  named  "tojcheck"  to  pass  to  libpdtab  so  a 
list  of  potential  target  vehicles  within  a  specified  range  can  be  generated. 

6.  CaU  the  function  pbt_g«t_v«hicl«s(cz,  cy,  range,  to.check)  to  get  the  to_check  list  (a  list 
of  vehicles  that  are  within  range).  The  missUe  locus  (cx,  cy)  was  determined  by  interpolating  a 
location  midway  between  the  old  and  new  positions.  The  range  was  determined  by  the  distance 
between  the  old  and  new  positions,  the  upper  bound  size,  and  the  >error  threshold  between 
actual  locations  and  locations  used  by  libpbtab  (the  position-based  vehicle  table). 

7.  Remove  the  vehicle  id  of  this  missUe  from  the  to_check  list. 

8.  If  the  count  of  vehicles  in  the  Ust  is  zero,  then  remove  the  types  DET.PLATFORMS  and 
DET3IISSILES  from  the  types-to-check  Ust.  This  means  there  is  no  need  to  check  the  vehicle 
table  at  all. 
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9.  If  there  are  no  types  left  in  the  types-to-check  list,  exit. 

10.  If  this  missile  is  not  stationary,  then  perform  whichever  type  of  fidelity  processing  is  indicated 
for  this  missile  (either  high  fidelity  or  low  fidelity  processing).  The  processing  for  these  fidelity 
types  differs  in  the  choice  of  possible  targets.  BasicaUy,  the  processing  consists  of  checking 
whether  the  distance  squared  to  each  vehicle  in  the  list  of  potential  targets  has  achieved  a 
local  minimun  and  whether  this  local  minimum  has  occurred  at  a  distance  which  is  less  than 
the  minimum  detonation  radius.  Then  of  these  distances,  pick  the  minimum.  A  more  detailed 
description  of  the  detonation  detection  algorithm  is  presented  below. 

The  detonation  detection  software  performs  the  following  actions: 

1.  For  each  possible  target,  determine  if  it  is  a  candidate  for  detenotation.  A  target  is  a  candidate 
for  detonation  when  the  missile's  closest  point  to  target  has  just  been  passed.  This  is  calculated 
by  comparing  the  missile’s  current  distance  to  target  with  the  missile's  old  position  distance 
to  target. 

2.  For  a  candidate,  calculate  its  potential  “hit^oint".  A  "hit^oint"  is  computed  to  be  the  pmnt 
on  the  line  segment  from  old.pos  to  new_pos  which  is  closest  to  the  current  location  of  the 
target,  veh[vcount].location.  It  is  not  decided  whether  the  target  was  hit  yet.  Find  the  point 
on  the  projected  path  of  the  target  that  is  closest  to  the  computed  "hit.4>(Mnt"  to  determine  if 
it  is  within  the  detonation  radius.  To  do  this,  project  the  position  of  the  target  vehicle  using 
its  current  velocity  ("anti-RVA")  and  find  the  point  on  its  trajectory  ("projecte<Lpos'')  that 
is  closest  to  "hit^oint."  If  this  "projected^os"  is  within  range,  classify  this  detonation  as  a 
hit.  If  this  "projected^os"  is  outside  the  detonation  radius,  classify  this  detonation  as  a  near 
miss. 


The  three  functions  that  can  be  called  to  handle  the  different  "hit”  classifications  are:  vehi¬ 
cle  jdetonation^etected,  vehiclejnearjniss_detected,  and  terrain jdetonation.detected. 

The  vehicle.detonation_detected  function  does  the  following: 

1.  Determine  the  detection  type  of  the  hit  object  (either  DETJ’LATFORMS,  DETJdlSSILES, 
or  DET BUILDINGS). 

2.  Invoke  the  detonation  callback  function  registered  with  det.class.init.  A  callback  function 
is  used  to  inform  another  safobj  sub-class  library  (such  as  libmissile)  of  the  detonation.  That 
library  might  need  to  modify  private  data  (for  example,  saving  the  missile’s  detonation  position 
and  the  target  id)  and/or  perform  an  action  (for  example,  send  an  impact  PDU  onto  the 
simulation  network). 


The  vehicle_near.Bi88.detectod  function  does  the  fdlowing: 
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1.  When  DEBUG_DETONATION  is  ON,  print  a  message  saying  that  the  object  passed  close  to 
this  target  and  print  the  distance  squared  between  the  missile  and  target. 

2.  Invoke  the  callback  function  registered  with  det.clasa.init.  Since  the  detonation  library 
really  only  figures  out  if  the  missile  got  within  a  given  radius  of  the  target,  iibmissile  needs  to 
decide  if  it  was  legitimate  for  the  the  missile  to  be  aware  of  this  condition.  For  example,  "Does 
the  missile  have  an  active  radar?"  or  "If  the  missile  depends  on  reflected  radar  emissions  from 
the  launching  aircraft,  is  the  aircraft  still  alive  and  the  radar  still  locked  on?" 

The  terrain_detonation_datect«d  function  does  the  following: 

1.  When  DEBUG J) ETON ATION  is  ON,  print  a  message  saying  that  the  object  detected  a 
detonation  with  either  trees,  building,  or  ground.  Also  print  the  impact  location. 

2.  Invoke  the  callback  function  re^stered  with  det.class.init  with  the  other  id  field  set  at  0. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libdetonation,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  detJnit 


void  det.initO 


det.init  initializes  libdetonation.  Call  this  before  calling  any  other  libdetonation  functions. 


2.2  det^lassJinit 

void  det.class.initCparant.class,  callback) 

CLASS.PTR  parent. class ; 

DET.CALLBACK  callback; 

‘parent. class’ 

Spedfies  the  parent  class 

‘callback’ 

Spedfies  the  function  to  call  when  detonations  occur 

det.class.init  creates  a  handle  for  attaching  detonation  dass  information  to  vehicles.  The 
parent.class  is  one  created  with  class.declare.class.  The  callback  function  should  be  de- 
dared: 


void  callbackCvehicle.id,  position,  det.type,  other.id,  target.position) 
int32  vehicle.id; 
float64  posit ion [33: 
uint32  det.type ; 
int32  other.id; 
float64  target .postion [33 ; 


This  is  called  when  a  detonation  occurs.  The  position  sent  is  the  point  of  detonation  and 
target.postion  is  the  estimated  position  of  the  target  at  that  time.  The  det.type  code  is  one  of 
the  following: 
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DET.TREES 

Indicates  proximity  to  a  treeline  or  canopy  edge. 

DET_BUILDIHGS 

Indicates  proximity  to  a  building  or  other  structure.  If  the  other  structure  is  represented 
on  the  network,  the  vehicle  ID  of  that  structure  will  be  provided. 

DET.GROUND 

Indicates  a  detonation  due  to  proximity  to  the  ground. 

DET_PLATFORMS 

Indicates  proximity  to  a  platform  (vehicle,  DI,  etc.). 

DET.HISSILES 

Indicates  proximity  to  a  missile  (an  entity  on  the  network  with  a  aunition  type). 
DET_NEAR_MISS 

Indicates  a  near-miss  of  a  target  on  the  detonation  list 

If  the  collided  entity  exists  in  the  vehicle  table,  its  ID  is  given  in  the  other.id  field.  For 
detonations  with  terrain  features,  the  other.id  will  be  zero. 


2.3  det-create 

void  det.create (vehicle. id,  paras) 

int32  vehicle. id; 

DETOHATIOH.PARANETRIC.DATA  *pazas; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘paras’  Specifies  initial  parameters 

det.create  creates  the  detonation  class  information  for  a  vehicle  and  attaches  it  to  the  vehicle’s 
libclass  user  data. 


2.4  det_destroy 


void  det.destroyCvehicle.id) 
int32  vehicle. id; 
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‘vahicle.id’ 

Specifies  the  vehicle  ID 

dat.destroy  frees  the  detonation  class  information  for  a  vehicle. 


2.5  det-add -target 

void  det_add_target(vehicle_id,  target.id) 
int32  vehicle. id; 
int32  target.id: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘target.id’ 

Specifies  the  vtab  ID  of  the  target  to  be  added 
det. add. target  adds  a  target  to  the  list  of  detonation  candidates  for  a  missile. 


2.6  detulelete-target 

void  det.delete.targetCvehicle.id,  target.id) 
int32  vehicle. id; 
int32  target.id; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘target.id’ 

Specifies  the  vtab  ID  of  the  target  to  be  deleted 


det.delete.target  deletes  a  target  from  the  list  of  detonation  candidates  for  a  missile. 


2.7  det-clear Jist 


void  det.clear.listCvehicle.id) 
int32  vehicle.id; 
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‘vehicle. id’ 

Specifies  the  vehicle  ID 

det.clear.list  clears  the  list  of  detonation  candidates  for  a  missile. 


2.8  det_tick 

void  det_tick(vehicle.id,  ctdb) 
int32  vehicle.id; 

CTDB  ectdb; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘ctdb’  Specifies  the  terrain  database 

det.tick  ticks  the  detonation  sub-class.  During  the  tick,  if  a  detonation  is  detected,  a  />acket 
may  be  sent  and  the  callback  function  passed  to  det.class.init  may  be  invoked. 


ADST-TR-W003268 


LibDI 


Table  of  Contents 


1  Overview . 1 

2  Examples . 5 

3  Functions . 7 

3.1  disinfJnit . 7 

3.2  disinf_classJmt . 7 

3.3  disiiif_tick . 7 

3 .4  disinLcoUision . 8 

3.5  disinf-damage . 9 


Chapter  1:  Overview 


1 


1  O  verview 


Libdi  implements  an  instance  of  the  hull  class  of  components.  It  provides  a  low-fidelity  model 
of  DI  vehicle  dynamics.  Capabilities  are  modeled  only  to  the  second  order  (maximum  velocity, 
maximum  acceleration),  and  they  depend  upon  the  soil  type.  Unlike  previous  models,  the  param¬ 
eters  for  each  soil  type  are  specified  in  a  data  file,  so  the  software  does  not  need  to  be  modified  to 
accommodate  new  types  of  terrain. 

The  parameters  of  a  DI  vehicle  are  specified  in  its  configuration  file  as  follows: 


(DI  (soils  (<intsgsr  soil  t7p«>  (nax.spssds  <lloat  lorvard  KPH> 

<float  rsvsrss  KPR>) 
(maz.accsl  <float  mps2>) 
(maz.dscsl  <float  Bips2>) 
(max.turn  <float  dps>) 
(max.cliab  <float  dsgrss8>) 
(dust.spseds  <float  8BallKPH> 
<float  msdiumXPH> 
<float  larg«KPB>)) 

(<integsr  soil  typs>  (nax.spssds  <float  KPH> 

<float  rsvsrss  KPR>) 
(naz.accsl  <float  mpn2>) 
(naz.dscsl  <float  nps2>) 
(naz.tum  <float  dps>) 
(naz.clinb  <float  dsgrsss>) 
(dust.spssds  <float  snallKPR> 
<float  nsditinKPH> 
<float  largsKPH») 

...) 

(fusl.usags  (<float  8pssdl>  <float  spssd2>  ...) 

(<float  ratsl>  <float  rats2>  ...}) 

) 


The  parameters  specified  for  soil  type  0  (or  the  first  soil  type,  if  no  0  type  is  provided)  are  used 
as  a  default  when  on  a  soil  type  not  in  the  list. 


To  indicate  that  the  vehicle  should  not  kick  up  any  dust  on  a  kind  of  soil,  specify  a  speed  which 
is  higher  than  the  maximum  the  vehicle  can  travel  across  that  soil. 

The  fueljusage  table  consists  of  a  list  of  speeds  in  kilometers  per  hour,  with  a  list  of  corresponding 
consumption  rates  in  liters  per  hour.  If  an  older  vehicle  parameter  file  is  used,  with  a  scalar 
fuel-usage  figure,  it  will  ignore  it  and  use  the  internal  default  corresponding  to  8  kilometers  per 
liter.  The  minimum  table  size  is  one  speed/rate  pair. 
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Applications  interface  to  the  DI  model  primarily  through  the  iibhulls  interface.  The  most 
efficient  interface  for  controlling  vehicle  motion  is  HULLS.SET.DIRECTIQN.SPEED.  All  interfaces  use 
only  two  dimensions  of  the  provided  parameters.  Also,  when  a  direction  vector  is  given  it  is  not 
necessary  to  make  that  vector  a  unit  vector.  Libdi  will  do  the  normalization  only  if  it  is  necessary 
(for  example,  if  the  vehicle  is  already  pointing  the  right  way,  no  normalization  is  needed). 

Libdi  supports  only  one  instantiation  per  vehicle  (i.e.,  a  vehicle  may  not  have  more  than  one  DI 
hull). 

The  libhuUs  library  defines  a  common  set  of  functions  (and  the  semantics  of  those  functions) 
which  are  invoked  on  instances  of  the  hulls  class  (such  as  those  instantiated  by  libtracked  or  libfwa). 
It  is  possible  to  modify  the  DI  model  by  changing  an  exisiting  hulls  interface  function  or  by  adding 
a  completely  new  function. 

To  modify  an  existing  libdi  interface  function  would  require  the  following  actions: 


1.  If  the  change  occurs  only  in  the  function  body,  only  change  the  function  code  in  the  libdi 
library.  If  the  change  occurs  to  the  function’s  argument  list,  change  the  function  code  in 
both  the  libdi  library  and  the  hulls  interface  structure  definition  found  In  libhuUs.h.  Also  to 
maintain  the  common  hulls  interface,  change  the  code  for  the  modified  function  in  any  other 
hull  specific  component  libraries  (such  as  libfwa  or  libmissile). 

2.  Recompile  ModSAF. 

To  add  an  additional  libdi  function  to  the  current  model  would  require  the  following  actions: 

1.  Write  the  function  as  part  of  the  libdi  library.  The  function  is  written  in  the  code  which 
manages  the  libdi  class  information  attached  to  each  vehicle  (di-class.c). 

2.  Add  the  function  and  its  declaration  to  any  of  the  other  hull  specific  component  libraries.  This 
maintains  the  common  hulls  interface. 

3.  In  the  libdi  source  code  that  handles  libhuU  initialization  processing,  include  a  function_nufflber , 
function  entry  identifying  the  new  function  for  the  cnpnt  .define,  instance  function  and  ev¬ 
ery  other  hull  instance  library  (libfwa,  libmissile,  etc.). 

4.  In  libhulls.h,  add  an  entry  to  identify  the  new  macro  and  associate  it  with  a  function  code 
number.  This  new  addition  means  that  the  number  of  hulls  functions  must  be  incremented  by 
one.  The  hulls  interface  structure  definition  that  appears  in  libhulls.h  must  include  a  structure 
to  define  the  new  function's  argument  list. 

5.  Recompile  ModSAF. 
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To  replace  this  DI  model  with  a  completely  different  one  would  require  the  following  actions: 

1.  Decide  on  the  get  functions  and  set  functions  that  would  be  required  in  the  new  model.  Try  to 
map  these  needed  functions  to  the  existing  hulls  interface.  A  function  can  map  if  its  argument 
list  can  remain  the  same.  Functions  that  can  not  map  must  be  added  to  the  hulls  interface. 

2.  For  those  functions  that  can  map  to  the  existing  hulls  interface  but  whose  code  body  you 
want  to  change,  edit  the  code  for  the  function  in  the  Ubdi  source  hie  that  contains  the  code  to 
manage  the  libdi  class  information  (dijclass.c). 

3.  For  those  functions  that  can’t  map  to  the  existing  hulls  interface,  add  an  additional  function 
to  the  hulls  interface.  The  addition  procedure  was  described  above. 

4.  Recompile  ModSAF. 
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2  Examples 

To  get  the  component  number  of  my  hull: 
extern  int32  ny.hull: 

if  ((my.hull  ■  capnt.locatefvehicle.id,  reader. get .symbol ("hull")))  ■■ 
CMPMT.HOT.FOUHD) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  hull\n",  vehicle.id); 

To  then  give  a  command  to  that  hull: 
if  (my.hull  !-  CMPMT.NOT.FOUND) 

HULLS_SET.DIRECTION_SPEED(vehicle_id,  hull,  dirvec,  speed,  0.0,  0.0); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libdi,  including  the  format  and  mean 
ing  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  disinfJnit 


void  dislnf.initO 


disinf  _init  initializes  libdi.  Call  this  before  calling  any  other  libdi  functions. 


3.2  disinf-class Jnit 


void  disinf. class.initCparent.class) 
CLASS.PTR  parent.claas; 


‘parent.class’ 

Class  of  the  parent  (declared  with  class.doclars.class). 


disinf.claas.init  creates  a  handle  for  attaching  DI  class  information  to  vehicles.  The  par- 
entjclass  is  one  created  with  classjdeclarejclass. 


3.3  disinfjtick 


void  disinf.tickCvohiclo.id,  ctdb) 
int32  vshiclo.id; 

CTDB  *ctdb; 

‘vehicls.id’ 

Specifies  the  vehicle  II) 

‘ctdb’  Specifies  the  terrain  database  the  vehicle  is  operating  on. 
disinf.tick  ticks  the  DI  hull  <lvnamirs  model. 
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3.4  disinf-collision 


void  disinf.collisionCvehicle.id,  position,  coll.type, 

other.id,  other.msss,  other.velocity) 

int32  vehicle. id; 

floated  position [3] ; 
uint32  coll.type: 
int32  other.id: 
floated  other .mass; 
floated  other.velocity [3] : 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘position’ 

Specifies  the  position  of  impact  in  world  coordinates 

‘coll.type’ 

Specifies  the  type  of  collision 

‘other.id’ 

Specifies  the  vehicle  ID  of  the  other  party  (or  0  if  terrain) 

‘other .mass’ 

Specifies  the  mass  of  the  other  party 
‘other.velocity’ 

Specifies  the  velocity  of  the  other  party 

disinf. collision  tells  the  DI  hull  dynamics  model  that  a  collision  occured.  The  cdLtype 
should  be  one  of  the  libcollision  constants: 


COLL.TREES 

Indicates  crossing  a  treeline  or  canopy  edge. 

COLL.BUILOIKGS 

Indicates  crossing  a  building  or  other  structure.  If  the  other  structure  is  represented 
on  the  network,  the  vehicle  ID  of  that  structure  should  be  provided. 

C0LL.GR0Um) 

Should  not  be  checked  for  ground  vehicles. 

C0LL.PUTF0RIIS 

Indicates  intersecting  a  platform  (vehicle,  DI,  etc.). 

COLL.MISSILES 

Indicates  intersecting  a  missile  (an  entity  on  the  network  with  a  monition  type. 
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3.5  disinf-damage 

void  disinf.daaageCvehicle.id,  damage) 
iiit32  vehicle.id; 
int32  damage: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘damage’  Specifies  whether  the  DI  dynamics  should  simulate  being  damaged 

diaisf  .damage  tells  the  DI  hull  dynamics  model  that  it  is  damaged  (or  not)  depending  on  the 
boolean  value  of  the  damage  flag. 


ADST-TR-W003268 


LibDISConst 


Table  of  Contents 


1  Overview . 

1.1  Examples . 

2  Functions . 

2.1  disconst  Jnit . 

2.2  disconst^rint . 

2.3  disconst..gaise^imnet.tojdts . 

2.4  disconst^ise^isJo^imnet . 

2.5  discoast^ppearance-simiiet_to_dis 

2.6  disconst^ppearance_dis_to^imnet 

2.7  dlscoQstjcapabillties-simaet.tojdis 

2.8  dlsconst_capabilities_dis_to^imnet 


Chapter  1:  Overview 


1 


1  Overview 


LibDISConst  performs  conversions  between  SIMNET  and  DIS  constants  for  object  type  (guise) 
specification,  appearance  modifiers,  and  capabilities.  The  object  type  translations  are  specified  in 
a  data  file  (‘disconst.rdr’).  The  appearance  and  capabilities  translations  are  hard-coded  (speci¬ 
fication  of  these  translations  via  a  data  file  would  be  very  difficult,  since  SIMNET  and  DIS  are  not 
very  similar  in  the  way  they  specify  those  items). 

Internally,  the  translations  are  stored  in  two  formats; 

•  The  SIMNET  to  DIS  translations  are  stored  in  a  libOTMatch  format  database  (see  section 
‘Overview’  in  LibOTMatch  Programmer’s  Manual). 

•  The  DIS  to  SIMNET  translations  are  stored  in  a  n-ary  tree,  each  node  of  which  contains  an 
array  of  sub-trees  which  are  selected  by  the  value  of  a  field  of  the  DIS  entity  type.  Since  all  of 
the  fields  except  country  are  within  the  range  0-255  (and  most  are  less  than  20),  this  selection 
is  done  using  a  direct  map  (no  searching).  Country  codes  are  mapped  down  to  a  few  small 
integers  using  a  second-level  map,  to  allow  a  direct  map  scheme  to  be  used  within  the  search 
tree  for  countries  as  well. 

The  source  data  for  the  translations  comes  from  the  data  file  ‘disconst  .rdr’.  It  contains  the 
following  sections: 

TraversaJ  Instructions 

Although  all  DIS  entities  are  described  using  the  same  taxonomy  (Kind,  Doaaiu, 
Country,  Category,  Sub-category,  Specific,  Extra),  not  all  entity  kinds  use  all 
the  fields.  Also,  different  entity  kinds  traverse  the  fields  in  different  orders  (for  plat¬ 
forms,  Domain  selects  the  meaning  of  Category;  for  munitions,  Category  selects  the 
meaning  of  Domain).  Thus,  the  first  thing  specified  in  the  data  file  is  a  default  order  of 
traversal,  and  special  traversals  for  selected  kinds.  The  traversal  instructions  take  the 
general  form: 

( 

(<DIS  Kind  for  which  inatructiona  apply> 

DISKind  <field>  <field>  <field>  ...} 

) 

The  first  traversal  in^trnriinn  is  the  default. 

Country  Codes 

For  compactness,  and  to  .\lUiw  both  DIS  1.0  and  DIS  2.0  object  specifications  within  the 
same  data  file,  the  ronntnes  are  stored  internally  using  a  lookup  table.  The  translations 
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refer  to  the  countries  by  name.  This  name  is  used  as  the  key  into  a  lookup  table.  The 
lookup  table  takes  the  general  form: 

( 

("<country  naa«>"  <DIS  1.0  coda  nufflbar>  <DIS  2.0  coda  nu]iibar>) 

•  •  • 

) 

All  countries  referenced  in  the  next  section  must  appear  in  this  lookup  table. 
Translations 

Next  come  the  SIMNET  to  DIS  translations  (the  software  deduces  the  DIS  to  SIMNET 
translations  from  this  list  at  startup).  The  translation  table  takes  the  general  form: 

( 

(<SIMNET  Object  Typa>  (<Kind>  <Domain>  "<Country>" 

<Catagory>  <Sub-category>  <Spacific> 
<Extra>)) 

•  •  • 

) 

All  the  fields  except  Country  are  small  integers  (Kind  and  platform  Doaain  macros  are 
supplied  at  the  top  of  the  file).  Country  should  be  a  string  which  matches  one  of  the 
countries  in  the  Counry  Code  table,  above. 

Order  is  significant  in  two  cases: 

1.  If  more  than  one  SIMNET  object  type  corresponds  to  a  smgjle  DIS  entity  type, 
the  first  one  listed  will  determine  the  resulting  DIS->SIMNET  translation. 

2.  If  a  DIS  entity  type  which  is  not  in  the  table  is  translated  to  a  SIMNET  object 
type,  it  will  default  to  the  first  object  encountered  which  matches  the  most  fields 
earliest  in  the  traversal  order  (analogous  to  the  libOTMatch  defaulting  scheme). 

Thus,  more  common  object  types  should  be  listed  earlier  in  the  data  file. 

The  data  file  is  complete  as  of  the  initial  writing  of  this  document.  There  are  many  defined  SIM¬ 
NET  object  types  for  which  no  obvious  DIS  equivalent  exists  (including  almost  all  the  structures). 
These  problem  translations  are  noted  in  the  data  file  with  comments. 

To  print  the  translation  table  in  a  format  similar  to  the  DIS  standard,  mako  test,  then  run 
test  1.  The  test  program  can  also  peform  conversions  from  the  command  line  (run  test  with  no 
arguments  for  usage  instructions). 


1.1  Examples 

The  test  program  ‘test  .c’  gives  examples  of  how  to  initialize  libDISConst,  and  perform  object 
type  conversions. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libDISConst,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  disconstJnit 

int32  disconst.initCdata.path.  reader.flags,  dis.version) 
char  *data_path; 
uint32  reader.f lags ; 
int32  dis.version: 

‘data.path’ 

Specifies  directory  where  data  file  is  expected 

‘reader. flags’ 

Specifies  libreader  format  file  reading  flags 
‘dis.version’ 

Specifies  version  of  DIS  in  use 


disconst.init  initializes  libdisconst,  causing  it  to  read  its  data  file  (‘disconst  .rdr’)  from  the 
passed  directory  (or  ‘.’)  using  the  specified  reader  .flags.  The  return  value  is  0  for  success,  or 
one  of  the  libreader  reader.read  return  values. 


2.2  disconst-print 

void  disconst .pr into 

disconst.print  prints  the  DIS->SIMNET  translation  tree  in  a  manner  similar  to  the  DIS 
specification. 


2.3  disconst^uise_simnet_to jdis 


void  disconst.guise.siinnet.to.dis(si]nnet ,  dis,  warhead) 
Ob j  ectType  *s ionet ; 
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DIS.EimTY.TYPE  *di8; 

DIS.WARHEAO.TYPE  «vaxhead; 

‘sinnec’  Specifies  SIMNET  object  type 
‘die’  Returns  DIS  entity  type 
‘uarhead’  Returns  DIS  warhead  type 

di8con8t.gttiBa.8iiBnet.to.di8  converts  a  SIMNET  guise  to  its  DIS  equivalent.  If  the  varhead 
is  not  desired,  pass  NULL. 


2.4  disconst-guise_dis-to-simnet 

void  di8con8t.gui8e.di8.to.8i]Bnet(di8.  varhead,  ainnet) 

DIS.ENTITY.TYPE  *dia; 

DIS.HARHEAD.TYPE  *varhead: 

Ob j  ectType  *8 innat ; 

‘dia’  Specifies  DIS  entity  type 
’warhead’  Specifies  DIS  warhead  (or  MULL) 

‘ainnat’  Returns  SIMNET  object  type 

diBconat.guiBa.diB.to.aianot  converts  a  DIS  guise  to  its  SIMNET  equivalent.  If  the  war¬ 
head  is  not  relevant,  pass  MULL  for  warhead. 


2.5  disconst-appearance^imnet.to.jdis 


void  di8const.appaaranca.8ianat.to.di8(di8.typa,  aiainet,  die) 
DIS.EMTITY.TYPE  *di8.typa; 

uint32  *8iBmot ; 

DIS.ENTITY.APPEARAMCE  adia; 


‘dia.type’ 

Specifies  DIS  entity  type 
‘aiamat’  Specifies  SIMNET  appearance  bits 

‘dia’  Returns  DIS  appearance  bits 


di8con8t.appaaranca.8iBmat.to.di8  converts  a  SIMNET  appearance  to  its  DIS  equivalent. 
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2.6  disconst.jippearance.dis jto-simnet 


void  disconst.appearance.dis.to.sinmetCdis.type,  dis,  sianet) 
DIS.EirnTY_TYPE  •dis.type; 

DIS_EHTITY_APPEARANCE  *di8; 
uint32  *8ian«t; 


‘di8_type’ 

Specifies  DIS  entity  type 
‘die’  Specifies  DIS  appearance  bits 

‘sinnet’  Returns  SIMNET  appearance  bits 


di8con8t_appearance_di8_to_8i]Bnet  converts  a  DIS  appearance  to  its  SIMNET  equivalent. 


2.7  disconst^apabiiities.simnet.to.dis 


void  di8Con8t_capabiliti«8.8iBnet.to.dis(8ianet,  dis) 
VehicleCapabilitiea  *8iBmet; 
DIS.ErriTy,CAPABILITIES  *di8; 


‘siamet’  Specifies  SIMNET  capabilities 

‘dis’  Returns  DIS  capabilities 

disconst.ctqiabilities.sumet.to.dis  converts  a  SIMNET  capabilities  record  to  its  DIS 
equivalent. 


2.8  disconst^apabiiities^i8.to.simnet 

void  disconst.capabilities.dis.to.sismetCdis,  sianet) 

DIS.EITm.CAPABILITIES  edis; 

VehicloCapabilitias  *sianet; 

‘dis’  Specifies  DIS  capabilities 

‘sianet’  Returns  SIMNET  capabilities 

disconst.capabilities.dis.to.sianet  converts  a  DIS  capabilities  record  to  its  SIMNET 
equivalent. 
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1  O  verv  iew 


Llbdither  uses  a  fairly  standard  method  for  generating  shading  dithers. 

A  program  using  libdither  will  first  make  a  dither-generating  matrix  using  the  function  dither  .matrix  ( ) . 
The  function  generates  a  NzN  dither  matrix  where  II  is  a  power  of  2.  The  algorithm  is  based  on  the 
Judice,  Jarvice,  Ninke  recunence  relation  detailed  in  Foley,  vanDam,  et.  al.  (II  edition,  p.  571). 

The  dither  matrix  can  be  used  to  generate  dither  bitmaps.  For  example,  the  2x2  dither  matrix: 


can  be  used  to  generate  the  following  bitmaps: 

00  10  10  11  11 
00  00  01  01  11 

These  bitmaps  can  be  generated  explicitly,  or  they  can  be  generated  on  an  as-needed  basis,  and 
copied  or  OR’d  into  other  bitmaps. 

Macros  are  provided  to  correctly  declare  the  matrix  (DITHER.NATRIZ)  and  bitmap 
(D1THER_BITNAPS)  data  structures,  as  well  as  a  macro  which  computes  the  number  of  unique 
bitmaps  which  can  be  generated  from  a  dither  matrix  of  a  given  size  (DITHER.C0U1IT). 
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2  Examples 


The  following  example  program  (called  ‘xtest  .c’  in  the  libdither  source  directory)  fills  the  root 
window  with  a  number  of  4x4  rectangles.  Each  rectangle  is  stippled  with  a  dither  corresponding 
to  its  distance  from  the  center  of  the  screen.  A  16x16  dither  pattern  is  used. 

Depending  upon  whether  tdef  ine  DO.RECTS  is  present,  the  program  will  either  use 
dither.bitnapsO  to  generate  stipples  for  a  GC,  or  it  will  use  dither. or ()  to  generate  one  large 
bitmap.  The  second  version  runs  about  15  times  as  fast,  due  to  the  reduction  X  traffic. 


/* 

idefina  DO.RECTS 
*/ 

•ifndaf  DO.RECTS 
•define  DO.BITMAP 
•endif 

•include  "libdither .h" 

•include  <X11/Xlib.h> 

•Include  <Xli/Xutil .h> 

•include  <stdio.h> 

•include  <aath.h> 

•define  SIZE  16 

•ifdef  D0.RECTS 
aainO 

Diaplay  *dp7; 
int32  screen; 

Hindov  root; 

GC  gc; 

int32  i,  x,  j; 
int32  w,  h,  Hv,  Hh; 
float64  d; 

DITHER.IUTRIX(Bat.SIZE) ; 

DITHER_BITIfAPS(bits,SIZE) ; 

PixMp  piz[DITHER.C0UHTCSIZE)3 ; 

/*  Make  the  dither  generating  natrix  */ 
dither .aatrix (SIZE,  mat); 

/*  Make  DITHER.COUMTCSIZE)  bitmaps  from  the  matrix  */ 
dither .bitmaps (SIZE,  mat,  bits); 
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/*  Open  the  display  device  */ 
dpy  *  ZOpenDisplayClfULL) ; 
it  (!dpy) 
exit  (2); 

/•  Find  the  screen  and  root  vindov  */ 
screen  «  Default Screen (dpy) ; 
root  ■  RootWindowCdpy,  screen): 

/•  Generate  DITHER.COUIfT(SIZE)  pizaaps  from  the  bitmaps  */ 
for(i-0;i<DITHER.CQUIIT(SIZE)  ;i+^) 

piz[i]  ■  ZCreateBitnapFroaOataCdpy.  root,  bitsCi],  SIZE,  SIZE); 

/*  Create  a  GC  for  filling  in  the  rectangles  •/ 
gc  ■  ZCreateGCCdpy,  root,  0.  NULL); 

ZSetForeground(dpy,  gc,  BlackPizelCdpy,  screen)); 
ZSetBackgroundCdpy,  gc,  WhitePizeKdpy,  screen)); 

ZSetFillStyleCdpy,  gc,  FillOpaqueStippled) ; 

/*  Find  the  size  of  the  screen  •/ 

V  ■  OisplayVidthCdpy, screen); 
h  ■  DisplayHeight (dpy, screen); 

Hw  ■  w/2; 

Rh  «  h/2: 

/*  Find  the  distance  that  the  furthest  rectangle  sill  fall  from  the 

*  center. 

*/ 

d  •  sqrt(Hv*Hv  *  Hh*Hh): 

/*  Fill  in  a  bunch  of  4z4  rectangles,  stippled  according  to  their 

*  distance  from  the  center  of  the  screen. 

*/ 

for  (y«0;y<h;y+»4) 
for  (x»0;z<w;z+»4) 

{ 

i  •  (DITHER.C0UIT(SIZE)-1)  * 

sqrt(CHs-z)e(Hsoz)  ♦  (Hh-y)*(Hh-y))/d; 

ZSetStippleCdpy,  gc.  pizCi]); 

ZFillRectangle(dpy.  root,  gc,  z,  y,  4,  4); 

> 


/*  Close  the  display  •/ 
ZCloseOisplay(dpy) ; 


•endif 


fifdef  D0.BmiAP 

mainO 

i 


ZImage  *image: 
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Display  *dipy; 
ist32  screen; 

Windoe  root; 

GC  gc; 

int32  i,  z,  y; 
int32  V,  h,  Hv,  Hh; 
floated  d; 

DITHER_MATRIX(Bat.SIZE) ; 
char  ebitfflap; 

/*  Make  the  dither  generating  smtriz  «/ 
dither .matrix (SIZE,  mat); 

/*  Open  the  display  device  */ 
dpy  •  XQpenDisplayCNULL) ; 
if  (!dpy) 
exit  (2); 

/«  Find  the  screen  and  root  irindos  */ 
screen  ■  Oef aultScreenCdpy) ; 
root  ■  RootHindo«(dpy,  screen) ; 

/*  Find  the  size  of  the  screen  *' 

V  •  DisplayWidthCdpy, screen): 
h  ■  OisplayHeight (dpy, screen) ; 

/*  Allocate  a  bitmap  big  enough  to  cover  the  vhole  screen  */ 
bitmap  ■  (char  *)malloc(h  *  ((v'*'7)/8)); 
bzero(bitmap.  h  *  ((s'*^7)/8)) ; 

/*  Create  an  XYBitmap  format  Xlstage  */ 

image  ■  XCreateImage(dpy,  MULL.  1,  XYBitmap,  0,  bitmi^, 

w,  h,  8,  (w*7)/8); 

/*  Find  the  distance  that  the  furthest  rectangle  will  fall  from  the 

*  center. 

♦/ 

He  •  w/2; 

Hh  «  h/2; 

d  ■  sqrt(Hv*Hw  *  Hh*Hh): 

/*  Fill  in  a  bunch  of  4x4  rectangles,  stippled  according  to  their 

*  distance  from  the  center  of  the  screen. 

*/ 

for  (y*0;y<h;y+«4) 
for  (x*0;x<w;x+»4) 

{ 

i  ■  (DITHER.C0UIT(SIZE)-1)  ♦ 

sqrt((Hw-x)*(Hw-x)  ♦  (Hh-y)*(Hh-y))/d; 
dither. or (SIZE,  i,  mat,  bitmap,  v,  h,  x,  y,  4,  4); 
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} 

/*  Create  a  GC  for  copying  the  iaage  */ 
gc  *  XCreateGCCdpy.  root,  0,  HULL) ; 
XSetForegroundCdpy,  gc.  BlackPizeKdpy,  screen}); 
XSetBackgroundCdpy,  gc,  WhitePizeKdpy,  screen)); 

/*  Copy  the  bitmap  to  the  screen  */ 

XPutlmageCdpy,  root,  gc.  image,  0,  0.  0,  0,  b,  h) ; 

/*  Close  the  display  */ 

XClosaDisplay(dpy) ; 

} 

tendif 
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3  Fu  n  ctio  n  s 


The  following  sections  describe  each  function  provided  by  lib  dither,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  dither-matrix 


void  ditherjoatrizCaize,  mat) 
int32  size; 

DITHER.NATRIXfaat.  size); 


‘size’  Specifies  the  size  of  the  dither  matrix 
‘inat’  Returns  the  dither-generating  matrix 

dither  .matrix  creates  a  dither  matrix  which  can  then  be  passed  to  dither  generating  functions. 


3.2  dither-bitmaps 

void  dither .bitmaps (size,  mat,  bits) 
int32  size; 

DITHER.NAT11IX(  mat,  size); 

DITHER.BITNAPS(bit8,  size); 

‘size’  Specifies  the  size  of  the  dither  matrix 
‘mat’  Specifies  the  dither  generating  matrix 

‘bits’  Returns  the  bitmaps 

dither  .bitmaps  creates  OITHER-COUKTCsize)  bitmaps  horn  the  dither  generating  matrix  (cre¬ 
ated  with  dither-matrizO).  bitsCi]  OOiCDITHER.COUHTCsize),  is  the  ith  bitmap,  and  can  be 
passed  to  X-windows  functions  such  as  XPutImageO,  or  XCreatePizm^FromBitmapDataO. 


3.3  dither^r 


void  dither. oz (size,  vhich.dither,  mat,  bitm^,  bitm^. width. 
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bitmap.height ,  xO.  yO,  area.vidth,  area.height) 
int32  size; 

int32  vhich.dither ; 

DITHER.HATRIXCmat.  size); 

char  obitmap; 

int32  bitmap.vidth; 

int32  bitmap.height ; 

int32  xO,  yO; 

izit32  area.vidth .  area.height ; 


‘size’  Specifies  the  size  of  the  dither 

‘uhich.dither’ 

Specifies  which  dither  to  generate 
‘mat’  Specifies  the  dither-generating  matrix 

‘bitmap’  Returns  the  bitmap 

‘bitmap.vidth,  bitmap.height’ 

Specifies  the  size  of  the  bitmap 

‘xO ,  yO’  Specifies  the  starting  location  within  the  bitmap 

‘area.«idth,  area.height’ 

Specifies  the  area  to  dither  within  the  bitmap 


dither.or  OR’s  in  an  area.vidth  x  area.height  section  of  the  vhich.ditherth  dither  gen¬ 
erated  from  the  matrix  mat.  The  upper  left  comer  of  the  dither  is  at  xO,  yO  of  the  bitmap. 


See  (undefined)  [dither'copy],  page  (undefined). 


3.4  dither-copy 


void  dither. copy (size,  vhich.dither,  mat,  bitmap,  bitmap.vidth, 
bitmap.height,  xO,  yO,  area.vidth,  area.height) 
int32  size; 

int32  vhich.dither; 

DITHER.KATRIX(mat,  size); 

char  ebitmap; 

int32  bitmap.vidth; 

int32  bitmap.height ; 

int32  xO,  yO; 

int32  area.vidth,  araa.height; 


‘size’ 


Specifies  the  size  of  the  dither 
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‘vhich.dither’ 

Specifies  which  dither  to  generate 
‘mat’  Specifies  the  dither-generating  matrix 

-bitmap’  Returns  the  bitmap 

‘bitmap  .width,  bitmap  .height’ 

Specifies  the  size  of  the  bitmap 

‘xO,  yO’  Specifies  the  starting  location  within  the  bitmap 
‘area.width,  area_height’ 

Specifies  the  area  to  dithor  within  the  bitmap 

dither.copy  works  just  like  dither.or,  except  that  zero  bits  in  the  dither  are  set  to  zero  in 
the  bitmap.  Hence,  dither.copy  runs  only  about  half  the  speed  of  dither.or. 

See  (undefined)  [dither ‘or],  page  (undefined). 
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1  Overview 


Because  of  limitations  in  network  bandwidth,  the  DIS  world  uses  the  concept  of  dead  reckoning 
(DR)  to  lessen  the  network  traffic  of  DIS  entities.  The  theory  is  that  if  the  (DR)  algorithm  used 
by  a  particular  entity  is  known,  the  position  (and  orientation  if  the  algorithm  specifies  it)  of  a 
remote  entity  can  be  approximated  until  the  next  actual  update  is  received.  On  the  sender’s  side, 
the  sender  calculates  the  actual  state  of  the  entity  and  then  compares  it  against  the  approximated 
state  that  the  world  assumes  as  truth.  If  the  two  states  deviate  by  more  than  a  specified  set  of 
thresholds,  the  sender  must  send  out  a  packet  updating  its  state  for  the  rest  of  the  players. 

Libdr  provides  a  set  of  generic  routines  which  can  be  combined  to  do  various  types  of  dead 
reckoning  algorithms.  It  assumes  a  cartesian  coordinate  system,  such  as  GCC  or  SIMNET’s  Level 
Metric,  but  is  independent  of  units;  the  parameters  -  position,  velocity,  time,  etc  -  must  be  specified 
consistently,  but  the  user  may  choose  the  units.  In  other  words,  if  position  is  specified  in  meters,  and 
time  in  seconds,  the  velocity  must  be  specified  in  meters/second.  It  can  not  be  kilometers/second 
or  meters/miUisecond.  Position,  velocity,  and  accdleration  must  be  also  be  specified  with  respect 
to  the  same  coordinate  system  (WORLD  vs  BODY). 

In  addition  to  the  dead  reckoning  routines,  libdr  also  provides  a  set  of  routines  to  do  poutional 
and  rotational  threshold  checking.  These  routines  can  be  used  in  conjunction  with  the  dead  reck¬ 
oning  routines  to  determine  whether  or  not  a  entity  has  exceeded  its  thresholds,  requiring  that  a 
packet  be  sent  out  to  update  its  position  in  the  world. 

All  linear  dead  reckoning  routines  are  supported  for  both  float32  and  fioat64  vectors.  Angular 
dead  reckoning  routines  using  3x3  matrices  for  rotation  are  supported  for  both  float32  and  float64 
matrices.  Angular  dead  reckoning  routines  using  quaternions  for  rotation  are  currently  supported 
for  floated  quaternions  only.  Threshold  routines  for  rotational  checking  are  supported  for  both 
floated  and  float32  matrices.  Threshold  routines  for  rotational  checking  using  quaternions  and 
positional  checking  are  supported  for  floated  only.  Elapsed.time  and  position  are  always  represented 
using  floated’s.  In  addition,  the  angular  dead  reckoning  routines  support  both  W0RLD-to30DY 
and  BODY-to.WORLD  matrices  as  well  as  quaternions.  The  naming  convention  for  these  functions 
is: 

32  bit  or  64  bit  foating  poiat 

Name  contains  32  or  64  at  or  near  end 

body  or  world 

Name  ending  in  body  or  vorld  indicates  that  rotations  are  specified  as  body.to.vorld 
or  vorld.to.body  respectively, 
matrix  or  quat 
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Name  contains  matrix  or  quat  at  or  near  end  indicates  that  rotations  are  specified 
using  a  3  X  3  matrix  or  quaternion  respectively. 

For  example,  the  64  bit,  first  order  angular  dead  reckoning  function  using  world.to-body  matrices 
is  dr_fir8t_order_angular_dr.matrix64.vorld. 

The  Functions  Chapter  specifies  the  versions  which  are  currently  supported.  The  prototype 
types  described  in  that  section  use  generic  terms  as  follows: 

scalar  s  Either  float32  s  or  f  loat64  s 
vector  V  Either  float32  v[3]  or  float64  vr3] 
matrix  m  Either  float32  mC3]  [3]  or  f loat64  m[3]  [3] 

quat  q  quaternion  which  contains  2  parts,  a  scalar,  referred  to  as  qscalar  and  a  vector, 
referred  to  as  qvector 

rotation  r 

Elither  matrix  or  quat 
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2  Examples 


The  program  ^dr.test',  found  in  'dr.test.c'  in  the  libdr  source  directory,  demonstrates  some 
possible  uses  for  libdr.  It  can  be  compiled  with  the  command  ‘make  dr.test’.  Due  to  the  nature  of 
the  test  cases,  they  do  not  determine  their  own  success  or  failure.  Their  output  must  be  analyzed 
by  the  tester  with  the  help  of  a  scientific  calculator. 


The  first  order  and  second  order  linear  dead  reckoning  routines  can  be  easily  combined  to  form 
the  following  algorithms,  defined  in  the  DIS  2.0  Standard.  The  3  letter  naming  conventions  can  be 
interpreted  as: 


F/R  :  Fixed  Rotation  or  1st  Order  Rotation 

P/V  :  Ist  Order  Position  or  2nd  Order  Position  (Velocity) 

W/B  :  Vorld  or  Body  Coordinates 

FPW  :  Fixed  Rotation.  First  Order  Position.  World  Coordinates 
Defined  as  Algoritha  2  in  the  DIS  2.0  Standard 
(DR  algorithm  used  in  SIMNET) 

RPW  :  First  Order  Rotation.  First  Order  Position.  World  Coordinates 
Defined  as  Algorithm  3  in  the  DIS  2.0  Standard 

RVW  :  First  Order  Rotation.  Second  Order  Position.  World  Coordinates 
Defined  as  Algorithm  4  in  the  DIS  2.0  Standard 

FVV  :  Fixed  Rotation.  Second  Order  Position,  World  Coordinates 
Defined  as  Algorithm  S  in  the  DIS  2.0  Standard 

FPB  :  Fixed  Rotation,  First  Order  Position,  Body  Coordinates 
Defined  as  Algorithm  6  in  the  DIS  2.0  Standard 

FVB  :  Fixed  Rotation,  Second  Order  Position,  Body  Coordinates 
Defined  as  Algorithm  9  in  the  DIS  2.0  Standard 


The  following  code  fragment  illustrates  how  the  routines  can  be  combined  to  execute  the  RPW 
algorithm.  The  ‘RPW’  is  specified  in  the  DIS  2.0  standard  as  DR  algorithm  3.  For  this  algorithm, 
first  order  linear  positional  dead  reckoning  as  well  as  first  order  rotational  dead  reckoning  is  ap¬ 
plied.  Initial  velocity  is  specified  in  WORLD  Coordinates.  Example  is  for  float64’s  using  an  initial 
BODY-to.WORLD  orientation  matrix. 
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/* 

*  Given  elapsed.tiae,  Initlal.poeition,  and  velocity,  a 

*  current .posit ion  position  is  calculated  and  returned  in 

*  *c\irTent .posit ion’ 

*/ 

float64  elapsed.time;  /*  tine  frm  vhen  initial.position  was 


accurate  until  now  *t 
float64  initial.position[3] ;  /*  position  before  DR  applied  */ 
float64  velocity [3];  /*  linear  velocity,  WORLD  coords  */ 
float64  current .posit ion [3] :  /*  position  after  DR  applied  */ 


dr.first.order.linear.dr64  (  elapsed.tiae,  initial.position,  velocity, 

current.position  ); 


/• 

*  Hie  angular  velocity  vector  only  changes  when  a  new  packet  arrives. 

*  To  save  coiqiute  cycles,  the  omega  and  axis  of  rotation  that  is 

*  extracted  from  the  vector  should  be  cached. 

* 

*  Given  an  angular  velocity  vector,  omega  (the  magnitude)  and  axis  of 

*  rotation  are  determined  and  returned  in  ‘omega*  and  ‘axis’. 

*/ 

float64  angular.velocityC3] :  /*  angular  velocity.  WORLD  coords  */ 

float64  omega;  /*  unpacked  angular  velocity  */ 

floated  axis [3] ;  /*  axis  of  rotation  */ 

dr.unpack.angular.velocity64  (  angular .velocity,  komega,  axis  ); 

/* 

*  Given  an  initial  BODY.to.WORLD  matrix.  elapsed.timn,  (»ega.  and 

*  axis  of  rotation,  a  current  BODY.TO.WORLD  matrix  is  calculated 

*  and  returned  in  ‘ current .body. to. world * . 

*/ 

floated  initial.body.to.worldCS] [3] ;  /*  BODY.to.WORLD  matrix  before  DR  */ 
floated  current .body.to.world [3] [3] ;  /*  BODY.to.WORLD  matrix  after  DR  */ 

dr.first.order.angular.dr.matrixed.bodj  (  elapsed.time,  omaga,  axis, 

initial.body.to.world , 
current.body.to.world  ); 
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3  Fu  n  ctio  n  8 

The  following  sections  describe  each  function  provided  by  libdr,  including  the  format,  meaning 
of  its  arguments,  and  meaning  of  its  return  values  (if  any). 


3.1  dr-first_orderJinear_dr 

void  dr.first.order.linear.dr  (  elapsed.tiae,  initial.position, 

initial. velocity,  current .position  ) 

float64  elapsed.tine; 
vector  initial .posit ion [33 ; 

x'  ~>T  initial_velocity[33 ; 

r  ctirrent  .posit  ion  [33 : 

‘elapsed.tiBe’ 

Time  elapsed  between  initial.position  and  c\urrent. posit  ion 

‘initial.position’ 

Position  to  dead  reckon  from. 

‘initial  velocity’ 

Velocity  to  apply  to  initial.position  to  calculate  current.position. 
‘current.position’ 

New  position  after  dead  reckoning;  return  value. 

Available  formats: 

•  dr_fir8t.ordor_linear.dr64 

•  dr_fir8t_ordor_linear.dr32 

dr.f  ir8t.ordor_linear_dr64  performs  first  order  linear  dead  reckoning  using  the  equation: 


P  ■  p_0  ♦  (v.O  *  t) 
p  :  current.position 


p.O  :  initial.position 
v.O  :  initial.velocity 
t  :  ol^sed_tiBe 
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3.2  dr-Becond_order Jinear.jdr 


void  dr.second.order.linear.dr  (  elapsed.tiM,  initial.position, 

initial.velocity ,  initial.acceleration, 
current .posit ion,  current.relocity  ) 

float64  elapsed.tiBe; 

vector  initial.positionCS] : 

vector  initial_velocityC33 : 

vector  initial_acceleration[3] ; 

vector  current.po8ition[3] : 

vector  current_velocityC3] : 

‘elapsed_tiBe’ 

Time  elapsed  between  initial.position/velocity  and  current  .position/velocity 

‘  init i al _pos it ion’ 

Position  to  dead  reckon  from. 

‘initial  velocity’ 

Velocity  to  apply  to  initial.position  to  calculate 
‘initial.acceleration’ 

Velocity  to  apply  to  initial.position  to  calculate  current.position  and  current.velocity 
‘current.position’ 

New  position  after  dead  reckoning;  return  value. 

‘current.velocity’ 

New  velodty  after  dead  reckoning;  return  value. 


Available  formats: 


•  dr.8econd.order.linear_dr64 

•  dr.8econd_order.linear.dr32 


dr_sacond.order_linear_dr64  performs  second  order  linear  dead  reckoning  using  the  equa> 
tion: 


p  ■  p_0  ♦  (v.O  *  t)  ♦  (0.5*a_0e(t*2)) 

V  ■  V.0+  a.O 

p  :  current.position  p.O  :  initial.position 

V  :  current.velocity  v.O  :  initial.velocity 

a_0  :  initial.acceleration 
t  :  elapsed.tine 
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3.3  drJirst^rder-anguiar-dr 

void  dr.first.order.angular.dr  (  elapsed.tiae,  oaega,  axis, 

initial.rotation,  current. rotation  ) 

float64  elapsed.tiae: 
scalar  omega; 
vector  axis ; 
rotation  initial.rotation; 
rotation  current. rotation; 


‘elapsed.tiae’ 

Time  elapsed  between  initial.rotation  and  current.rotation 
‘oaega’  Magnitude  of  angular  velocity. 

‘axis’  Axis  of  rotation  of  angular  velocity 

‘  init  ial.rot  at  ion’ 

Rotation  to  dead  reckon  from 

‘current.rotation’ 

New  rotation  after  rotational  dead  reckoning;  return  value. 
Available  formats: 


•  dr.f irst.order.angular.dr.aatrix64.body 

•  dr.first.ordor.angular.dr.matrix32.body 

•  dr.first.order.angular.dr.natrix64_«orld 

•  dr.f irst .order.angulaT.dr.aatrix32.vorld 

•  dr.first.order.angular.dr_quat64.world 

dr.first_order.angular.dr  performs  first  order  angular  dead  reckoning  using  either  cosine 
matrices  or  quaternions.  The  change  in  rotation  for  a  ^ven  time  frame  is  represented  by  the 
following  quaternion: 


h_  angle 

u 

t 

axis 

quat 

s.angle 


half.angle  of  rotation 
oaega 

elapsed.tiae 
axis  of  rotation 

intermediate  quaternion  for  change  in  rotation  (qscalar»  qvector) 
sin  (h_ angle) 


h. angle 
qscalar 
qvector [0] 


0.5*vt 

cos  (h_ angle) 
s.angle  *  axisCO] 
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qvectorCl]  ■  s.angle  *  azisCl] 
qvector[2]  ■  ■.angle  *  axis [2] 


If  the  input  rotation  is  a  quaternion,  the  initial.quaternion  is  concatenated  with  the  newly 
calculated  quaternion  to  return  a  quaternion  representing  the  dead  reckoned  rotation.  If  the  input 
rotation  is  a  matrix,  the  newly  calculated  quaternion  is  first  converted  to  a  direction  cosine  matrix. 
Two  matrices  are  then  concatenated  to  return  a  matrix  representing  the  dead  reckoned  rotation. 


3.4  dr-unpack_angular.velocity 

extern  void  dr .unpack. angular. velocity  (  angular. velocty,  omega,  axis  ) 
vector  angular. velocity: 
scalar  *omega: 

vector  axis : 

‘angular.velocity’ 

Angular  velocity  vector  in  Body  Coordinates. 

‘omega'  Pointer  to  Magnitude  of  angular  velocity;  return  value. 

‘axis’  Axis  of  rotation  of  angular  velocity;  return  value. 

Available  formats: 

•  dr.unpack.angular.velocity64 

•  dr.unpack.angular.velocity32 

dr.unpack.angular. velocity  takes  an  angular  velocity  vector  and  extracts  its  magniitude, 
omega,  and  its  axis  of  rotation,  axis.  This  action  need  only  be  done  whenever  the  angular  velocity 
changes,  not  each  time  one  performs  angular  dead  reckoning.  Therefore,  it  is  suggested  that  this 
routine  be  called  only  when  necessary  and  the  values  for  omega  and  axis  be  cached  for  efficiency. 
For  remote  entity  rotational  dead  reckoning,  this  would  need  to  be  called  for  a  particular  entity 
whenever  a  new  packet  arrived  for  it. 


3.5  dr^heckjocation .thresholds 

int32  dr.chsck.locac ion. thresholds  (  thresh.sq,  current.position 

dr.position  ) 


scalar  thresh.sq: 
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vector  ciirrent  .position; 

vector  dr.position; 

'thresh.sq:’ 

Square  of  the  position  threshold.  Must  be  in  units  consistent  with  those  used  for 
position. 

‘current.position’ 

Actual  position  of  the  local  entity 

‘dr.position’ 

Dead  reckoned  position  of  the  local  entity  since  the  last  packet  was  sent 

dr.check.location.thresholds  compares  the  current_position  with  that  of  dr^osition.  If 
‘current’  deviates  from  ‘dr’  by  more  than  the  specified  threshold,  it  returns  TRUE  (1)  indicating 
that  the  threshold  has  been  exceeded  and  therefore,  a  packet  should  be  sent.  Otherwise,  it  returns 
FALSE  (0).  The  algorithm  actually  requires  the  square  of  the  threshold.  Therefore,  for  efilciency, 
the  routine  takes  the  threshold  squared  as  a  parameter  rather  than  just  the  threshold  value  and 
assumes  the  user  can  cache  the  squared  value  instead  of  recomputing  it  every  time. 


3.6  dr-check-orientation. threshold 


int32  dr. cbeck.orient at ion. threshold  (  thresh,  current .rotation, 

dr .rot at ion  ) 

scalar  thresh; 
rotation  current .rot at ion; 
rotation  dr.rotation; 


‘thresh’  For  efficieny  purposes,  thresh  has  different  representations  depending  on  whether  or 
not  quaternions  or  matrices  are  used.  Given  a  rotational  threshold  in  radians,  thresh 
should  be  one  of  the  following: 

thresh  *  cos  (0.5  *  rotation  threshold)  ;  for  quaternions 

thresh  •  2  *  cos  (rotation  threshold)  *  1  ;  for  natrices 

‘current.rotation’ 

Rotation  representing  the  actual  orientation  of  the  entity 
‘dr.rotation’ 

Rotation  representing  the  dead  reckoned  approximation  of  the  orientation  of  the  entity. 


Available  formats: 
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•  dr. check. or i ent  at ion. threshold.mat r iz64 

•  dr.check.orientation.threshold.matriz32 

•  dr.check.orientation.threshold.quat 

dr.check.orientation.threshold  compares  the  current-rotation  with  that  of  the  drjotation. 
If ’current’  deviates  from  ‘dr’  by  more  than  the  specified  threshold,  it  returns  TRUE  (1)  indicating 
that  the  threshold  has  been  exceeded  and  therefore,  a  packet  should  be  sent.  Otherwise,  it  returns 
FALSE  (0).  As  with  dr_check.location.threflhold8,  the  algorithms  utilize  the  threshold  infor¬ 
mation  in  a  manner  which  can  be  precalculated  and  stored  for  future  use.  Details  of  the  format 
are  indicated  above  under  ‘threah’. 


3.7  dr-qu  at -transform 


void  dr.quat.tranafozB  (  arc,  rotation,  daat  ) 
vector  arc; 
quat  rot ; 
vector  deat; 

‘arc’  Initial  vector  that  is  to  be  transformed. 

‘rot’  Quaternion  which  represents  the  rotation  by  which  the  vector  is  to  be  rotated, 

‘deat’  Resulting  vector  after  transformation  has  been  applied;  return  value. 


dr.quat.tranafozm  rotates  a  vector  by  the  rotation  specified  in  the  quaternion.  Ultimatdy, 
this  belongs  in  a  quaternion  equivalent  of  libvecmat. 
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1  Overview 

Libechelondb  provides  a  database  of  named  standard  military  echelon  organizations  (also  re¬ 
ferred  to  as  Units),  which  can  be  used  as  templates  or  parts  of  templates  for  unit  creation.  Libech¬ 
elondb  uses  a  database  format  which  is  accessed  using  libotmatch  (see  section  ‘Overview’  in  Li- 
bOTMatch  Programmer’s  Manual).  A  GUI  for  unit  creation  can  access  this  library  to  allow  the 
initialization  of  a  unit  to  expand  into  the  initialization  of  an  entirely  instantiated  unit  hierarchy. 
Given  a  unit  to  be  created,  libechelondb  only  supplies  the  information  used  to  create  the  unit  and 
its  subordinates.  It  does  not  actually  create  the  unit  persistent  object  or  its  subordinate  persistent 
objects. 

The  types  of  information  stored  in  the  echelon  database  are  as  follows; 

The  collection  of  subunits  in  a  unit 

The  subunits  can  be  recursive  references  to  other  libechelondb  units.  For  example,  a 
platoon  can  contain  several  vehicles,  while  a  company  can  contain  several  command 
vehicles  and  several  platoons. 

The  way  vehicle  designations  are  generated  for  each  vehicle  or  unit 

For  example,  a  company  might  be  designated  as  "A  ",  the  first  platoon  in  that  company 
might  be  designated  as  "A1  ",  and  the  second  vehicle  in  the  first  platoon  might  be 
designated  "A12". 

The  order  of  promotion  between  units 

This  ordering  can  also  be  used  to  identify  unique  members  in  a  formation  of  units. 
This  information  is  stored  implicitly  in  the  data  file  by  the  ordering  of  the  subunits. 

The  echelon  database  is  stored  in  the  data  file  ‘echelondb .  rdr’.  The  format  of  this  data  file  is 
as  follows: 

( 

(<unit  idantifier>  (<8ubunit  identifiarl> 

<8ubunit  idantifier2> 

<8ubunit  idantifiar3> 

...)) 

<iiiora  \mit  d8finition8> 

) 

<unit  idantif  i8r>  is  the  object  type  representing  the  unit. 

A  <subunit  idantifier>  has  the  following  format: 
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([leaf  I  tree]  [<  vehicle  identifier>  I  <unit  idexitif  ier>]  <iiiarking  pattern>} 

leaf  meaAS  that  this  is  a  terminal  node  in  a  unit  hierarchy,  tree  means  that  this  subunit  should 
be  reexpanded  into  other  subunits  by  means  of  a  recursive  query  into  the  database.  A  unit  identifier 
could  be  specified  as  a  leaf  node,  which  would  imply  a  unit  hierarchy  containing  a  command  unit 
which  does  not  have  vehicles  in  it.  This  could  be  used  to  support  the  representation  of  aggregate 
simulation,  or  provide  empty  units  for  later  task  organization. 

The  <vehicla  identif  ier>  or  <unit  idencif  i«r>  specifies  the  object  type  of  the  unit  at  this 
level  in  the  hierarchy.  Vehicle  object  types  indicate  physical  vehicles  within  the  unit  hierarchy, 
while  unit  object  types  indicate  conceptional  aggregate  units  (with  or  without  vehicles  subordinate 
to  them). 

The  Cmarking  pattazn>  is  a  three  character  string  used  to  generate  markings  for  a  particular 
unit  in  the  hierarchy.  In  such  a  string,  the  character  ?  indicates  to  inherit  the  character  at  this 
position  from  the  superior  unit.  Thus,  a  vehicle  with  a  marking  pattern  of  "??4"  will  receive  a 
marking  of  "A24"  when  present  in  a  platoon  labeled  ''A2 

An  example  of  a  data  file  which  supports  platoons,  companies  and  battalions  of  Ml  tanks  is  as 
follows: 


( 

(unit.US.Ml.Platoon  ((leaf  vehicle.US.Ml 

(leaf  vehicle.US.Ml  ••??2”) 

(leaf  vehicle.US.Ml  ''??3") 

(leaf  vehicle.US_Ml  "??4''))) 

(unit.US.Ml.Coaqjany  ((leaf  vehicle.US.Ml  ''?66'') 

(leaf  vehicle.US.Ml  "?65") 

(tree  tmit.US.Nl.Platoon  "?1  ") 

(tree  unit.US.Ml.Platoon  "?2  ") 

(tree  unit.US.Ml.Platoon  '’?3  "))) 

(unit.US.Ml.BattalionHQ  ((leaf  vehicle.US.Ml  "HQl") 

(leaf  vehicle.US.Ml  "HQ2"))) 

(unit.US.Ml.Batallion  ((tree  unit.US.Ml.BattalionHQ  "H  ") 

(tree  unit.US.Ml.Con^any  "1  ") 

(tree  unit.US.Ml.Conipany  "2  ") 

(tree  unit.US.Ml.Con5)any  "3  "))) 

) 


The  algorithm  used  within  lil><><  !l••|o||l|||  fur  (|iieries  is  as  follows.  Queries  are  initiated  by  a  call 
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to  achdb.expand,  passing  in  an  array  of  the  ECHDB.DATA  structure  to  be  filled  out.  The  format  of 
the  ECHDB.DATA  data  structure,  which  will  be  filled  out  by  calls  to  echdb.expand,  is  as  follows: 


typedef  struct 

ObjectType 

int32 

int32 

char 

}  ECHDB.DATA; 


•chdb.data 

type; 
superior; 
promotion. index ; 
designationC4] ; 


type  is  the  vehicle  or  unit  object  type  of  the  unit. 

superior  is  the  array  index  of  the  unit  which  is  superior  to  this  unit.  The  topmost  unit,  which 
will  be  the  zeroth  element  of  the  array,  will  have  a  superior  of  -1. 

promotion.index  is  a  small  integer  representing  the  order  of  promotion  for  all  the  units  directly 
subordinate  to  the  superior  of  this  unit.  All  units  directly  subordinate  to  a  particular  superior  unit 
will  have  a  unique  promotion. index. 


designation  is  a  MULL  terminated  3-character  string  which  represents  the  designation  or  "bumper- 
number"  of  the  unit. 

Queries  into  the  database  by  echdb.expand  use  otia.query  (see  section  ‘otmjiuery’  in  LibOT- 
Match  Programmer’s  Manual)  to  access  the  data  for  a  particulair  unit.  First,  the  input  unit  is  used 
to  fill  out  the  zeroth  ECHDB.DATA  element.  Then,  if  a  unit  is  found  via  a  direct  otm_query  match, 
the  data  returned  by  otnuquery  is  used  to  fill  out  other  ECHDB.DATA  elements.  Recursive  queries 
are  performed  to  expand  any  elements  marked  as  tree  nodes. 


1.1  Examples 


The  test  program  ‘test.c’  demonstrates  initialization  of  libphysdb  and  all  the  libraries  it  de¬ 
pends  on.  The  output  of  a  sample  run  is  as  follows: 


cri]n8on->  test  unit.US.Ml.Company  "A  " 


Expansion  of  unit.US.Ml.Company  yields  18  subunits: 

0:  unit.US.Ml.Company,  marking  "A  ",  index  0, 
1:  vehicle.US.Ml,  marking  "A66".  index  0, 
2:  vehicle.US.Ml,  marking  "A65",  index  1, 


superior  is 
superior  is 
superior  is 


-1 

0 

0 
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3: 

unit.US.Ml.Platoon,  marking 

"A1  ", 

index  2,  superior  is 

0 

4: 

unit.US.Ml.Platoon,  marking 

"A2  ", 

index  3.  superior  is 

0 

5: 

unit.US.Ml.Platoon,  marking 

"A3  ", 

index  4,  superior  is 

0 

6: 

vehicle.US.Ml ,  marking 

"All". 

index  0,  superior  is 

3 

7: 

vehicle.US.Ml ,  marking 

"A12", 

index  1,  superior  is 

3 

8: 

vehicle.US.Ml,  marking 

"A13", 

index  2,  superior  is 

3 

9: 

vehicle.US.Ml,  marking 

"A14" , 

index  3,  superior  is 

3 

10: 

vehicle.US.Ml,  marking 

"A21", 

index  0.  superior  is 

4 

11: 

vehicle.US.Ml,  marking 

"A22" , 

index  1,  superior  is 

4 

12: 

vehicle.US.Ml,  marking 

"A23", 

index  2,  superior  is 

4 

13: 

vehicle.US.Ml,  marking 

"A24", 

index  3,  superior  is 

4 

14: 

vehicle.US.Ml,  marking 

"A31". 

index  0,  superior  is 

5 

15: 

vehicle.US.Ml.  marking 

"A32" . 

index  1,  superior  is 

5 

16: 

vehicle.US.Ml,  marking 

"A33" , 

index  2,  superior  is 

5 

17: 

vehicle.US.Ml ,  warn  ng 

"A34" , 

index  3,  superior  is 

S 

Chapter  2:  Functions 


5 


2  Functions 


The  following  sections  describe  each  function  provided  by  libechelondb,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  echdbJnit 

int32  echdb.init (directory,  flags) 
char  edirectory; 
uint32  flags; 

‘directory’ 

Specifies  the  directory  where  the  echdb  file  is  expected 
‘flags’  Specifies  reader  options  (see  section  ‘reader_read’  in  LibReader  Programmer’s  Manual) 

echdb.init  initializes  libechdb,  causing  it  to  read  its  data  file  ‘echdb. rdr’  from  the  specified 
directory.  The  flags  are  as  in  reader.read.  The  return  value  is  zero  if  the  read  succeeds,  or 
one  of  the  libreader  return  values:  READER.READ.ERROR  READER.FILE.IOT.FOUID. 

Note  that  the  libreader  function  reader.init,  the  librdrconst  function  rdc.init,  and  the 
libotnatch  function  otiB.lnit  must  be  called  before  this  function. 


2.2  echdb^xpand 


int32  echdb.expandC input,  input.designation,  output_length,  output) 
ObjectType  input; 
char  input.designation  □ ; 

int32  output.length; 

ECHDB.DATA  output  □; 


‘input’  Specifies  the  unit  to  look  up  in  the  database 
‘input.designation’ 

Specifies  the  ASCII  character  designation  -string  for  the  top  level  unit.  Designations 
for  lower  level  units  will  be  derived  from  this  string. 

‘output.length’ 

Specifies  the  maximum  number  of  outputs  to  fill  out. 
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‘output’  Specifies  an  array  of  ECHDB_DATA  records  to  fill  out  the  results  of  the  query. 

echdb.expand  looks  up  the  supplied  input  in  the  echelon  database  and  fills  out  the  units  in  the 
output  structure.  A  maximum  of  output.longth  units  will  be  filled  out.  echdb.expand  returns 
the  number  of  entries  in  output  that  have  been  filled  out  by  the  cajl.  input  is  always  returned  as 
the  zeroth  element  of  output.  If  input  is  not  found  in  the  echelon  database,  1  will  therefore  be 
returned. 
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1  O  vervie  w 


Libeditor  provides  a  facility  to  build  flexible  data-driven  editors  with  a  minimum  of  effort.  The 
library  is  an  integral  part  of  the  ModSAF  user  interface  architecture. 

The  programming  paradigm  used  is  as  follows: 

•  The  application  defines  a  data  structure  which  is  to  be  edited.  This  data  structure  is  fixed-size, 
although  it  may  contain  one  variable  length  field  (such  as  the  way  a  protocol  PDU  cannot  be 
larger  than  the  ethernet  packet,  but  it  may  contain  a  variable  amount  of  valid  information). 

•  The  application  defines  a  data  file  which  expresses  five  things  about  the  data  which  is  edited: 

•  The  name  of  the  editor 

•  The  memory  layout  of  fields  in  the  structure 

•  The  abstract  type  of  those  fields  which  may  be  edited 

•  The  way  to  initialize  each  field 

•  The  fields  which  impact  the  way  an  item  is  rendered 

•  The  application  passes  this  information  to  libeditor  at  startup,  at  which  time  a  user  interface 
is  constructed.  Optionally,  the  application  may  also  pass  functions  which  are  called  to  display 
the  item  bmng  edited,  and  to  process  the  edited  item  when  the  editor  is  exited. 

•  The  application  starts  the  editor  when  needed. 

The  following  sections  describe  the  five  main  sections  of  an  editor  definition  file. 


1.1  Name  Definition 

The  first  thing  which  must  be  specified  for  an  editor  is  its  name.  This  should  be  a  short 
description  of  what  the  editor  does.  For  example: 

(nama  "Text  Editor") 


1.2  Structure  Definition 

The  structure  is  defined  by  listing  each  member  of  the  structure  by  name,  and  then  specifying 
its  data  type,  and  optionally  its  length.  Padding  is  specified  by  using  the  reserved  label  padding 
and  specifying  how  many  bits  (must  be  a  multiple  of  8). 
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For  example,  the  structure: 


struct  foo 

{ 

intl6  bar: 
intl6  .paddingl; 
uint32  bazCS]; 

>; 


Would  be  defined  with  the  expression: 


(struct  (bar  intl6) 

(padding  16) 

(baz  uint32  3) 

) 


The  data  types  which  are  recognized  arc  as  follows: 

intS  uintS  intl6  uintl6  int32  uint32  float32  float64 
PointDescription  HunitionQuantity  ObjactIDTypa 

When  the  editor  is  created,  the  software  compares  the  size  of  the  structure  specified  by  this  data 
file  to  the  size  passed  in,  to  help  identify  inconsistencies  (usually  padding  problems). 

Note  that  C  compilers  pad  structures  for  efficient  access  to  data  over  the  bus.  In  general,  the 
following  rules  should  be  assumed: 

•  The  byte  of&et  to  a  primitive  type  which  is  n  bytes  long  will  be  a  multiple  of  n.  For  example, 
the  structure: 

struct 

intS  bar; 
intl6  baz; 

>  foo; 

has  a  byte  of  implicit  padding  between  bar  and  baz  so  that  baz  may  start  on  a  2  byte  offset 
into  the  structure. 

•  The  byte  offset  to  a  structure  within  a  structure  must  conform  to  the  strictest  alignment 
requirements  of  the  sub-structure’s  members.  For  example,  the  structure: 

struct 


intS  bar; 
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struct 

i 

intl6  baz; 
int32  bax; 

>  biz; 

}  foo; 

has  3  bytes  of  implict  padding  between  bar  and  the  sub-structure  biz,  and  2  bytes  of  implicit 
padding  between  baz  and  baz. 

•  The  total  size  of  a  structure  must  be  a  multiple  of  its  member’s  strictest  alignment  requirement. 
This  is  to  ensure  structures  can  be  placed  into  arrays.  For  example,  the  structure: 

struct 

int32  bar; 
intl6  baz; 

}  foo; 

has  2  bytes  of  implicit  padding  after  baz,  so  that  the  entire  structure  is  a  multiple  of  4  bytes 
(the  requirement  of  bar). 

•  Bitfields  generally  require  4  byte  alignment. 


These  rules  are  enforced  to  varying  degrees  on  different  hardware  platforms.  To  ensure  porta¬ 
bility,  always  declare  padding  explicitly: 


struct 

intS  bar; 
uintS  _padl ; 
uintl6  _pad2; 
int32  baz; 

>  foo; 


The  alignment  requirements  of  libeditor’s  basic  types  are  as  follows: 


intS  1 
uintS  1 
intl6  2 
uintl6  2 
int32  4 
uint32  4 
float32  4 
float64  8 
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Po intDes  cript ion 
4 

MtmitionQuantity 

4 

ObjectIDTyp* 
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1.3  Editor  Definition 

An  editor  is  defined  by  a  series  of  editables.  Each  editable  has  a  name,  a  type,  a  storage 
location  (which  is  a  reference  back  to  a  name  listed  in  the  struct  part  of  the  data  Ale),  and  other 
configuration  data.  For  example,  the  editor  definition  for  a  text  object  editor  might  look  like  this; 

(editor  ("Location"  PLACE  location) 

("Color"  CH00SE.0NE  color  HIDE  EDT.OVERLAY.COLORS) 

("Overlay"  OVERLAY  overlay) 

("Text"  STRING  text  5  length) 

) 

There  are  currently  16  different  types  of  editables,  which  are  described  in  the  following  sections. 

Note  that  in  the  usage  syntax  used  below,  Q  indicates  an  optional  field,  I  indicates  a  choice 
between  two  or  more  values,  and  O  indicates  a  list  of  values. 


1.3.1  ALTITUDE 


Usage 


(<nam«>  ALTITUDE  <8torage>) 

Internal  Representation 
Meters. 


Description 

An  altitude.  The  user  can  specify  distance  in  meters,  kilometers,  feet,  miles,  or  nautical 
miles. 


1.3.2  ANGLE 
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Usage 


(<nam«>  ANGLE  <storage>  [<ccv  boun(l>  <cw  bound>]) 

Internai  Representation 

Zero  refers  to  North,  and  the  viluo  increases  in  a  counter-clockwise  direction.  The 
units  are  either: 


•  BAMs,  if  stored  in  an  integer  type 

•  Radians,  if  stored  in  a  floating  point  type 

Description 

An  angle.  User  has  choice  of  specifying  in  degrees,  mils,  or  compass  units.  If  specified, 
the  counter-clockwise  bound  {<ccv  bound>)  and  clockwise  bound  (<cw  boimd>),  which 
should  be  an  integer  in  degrees,  are  represented  on  the  display  but  not  enforced. 


1.3.3  CHOOSE.ONE 

Usage 

(<naffl«>  CHOOSE.ONE  <storag«>  SHOWlHIDE 

{  (<choic«  naffl«>  <choice  valu«>  [<color  naffl«>])  } 

) 

Internal  Representation 

Integer  or  floating  point  value  of  current  choice. 

Description 

A  choice  of  one  item  from  a  list  of  choices.  The  editable  can  be  configured  such  that 
all  choices  are  presented  (SHOW),  or  with  only  the  current  choice  shown  (HIDE).  If  a 
color  name  is  given,  that  color  will  be  used  for  the  background  color  of  the  choice  (this 
is  used  in  the  pre-defined  macro  EDT.OVERLAY.COLORS  for  a  list  of  standard  overlay 
colors). 

Note  that  it  is  possible  to  use  CHOOSE.ONE  to  specify  a  choice  from  a  number  of  libreader 
symbols,  as  opposed  to  integer  or  floating  point  values.  To  do  this,  the  structure  definition  in  the 
program  would  be  specified  as; 

struct  ioo 

{ 

char  ^symbol; 

} 


and  the  structure  definition  in  •■<litittjr  definition  file  would  be  specified  as: 
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(struct 

(synbol  uint32) 

) 

Then,  strings  may  be  specified  for  <choics  valua>,  (as  well  as  in  initialization  section  of  the 
editor  definition  file),  as  follows: 


(editor 

("Symbol"  CHOOSE.ONE  symbol  HIDE 

("Labell"  "symbol-valuel") 
("Label2"  "symbol-value2“) 


The  CHOOSE.ONE  editable  type  also  w'iU  correctly  handle  the  case  where  the  target  structure 
type  is  an  array  of  characters,  and  the  value  is  a  string: 

(struct 
•  •  • 

(symbol  uintS  30) 

«  •  « 

) 

•  •  • 

(initial 
•  •  • 

(symbol  CONSTANT  "symbol-valuel") 

) 


1.3.4  CH00SEJ50ME 

Usage 

(<naffle>  CH00SE_S0HE  <value  8torage>  <length  8torage>  SHOW I  HIDE 
{  (<choice  naffle>  <choice  value>  [<color  naffle>])  } 

) 

Internal  Representation 

Array  of  integer  or  floating  point  values  which  were  selected,  and  the  number  of  elements 
of  that  array  which  are  used. 
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Description 

A  choice  of  several  items  from  a  list  of  choices.  The  editable  can  be  configured  such 
that  all  choices  are  presented  (SHOW),  or  with  only  the  current  choice  shown  (HIDE).  If 
a  color  name  is  given,  that  color  will  be  used  for  the  background  color  of  the  choice. 
The  values  of  all  the  selected  values  are  placed  in  successive  position  in  the  <value 
storaga>  array.  The  number  of  items  chosen  is  placed  in  the  <length  Btorag«>. 

Note  that  CH00SE.S0ME  can  be  used  to  choose  values  from  a  number  of  libreader  symbols,  as  in 
CH00SE_0NE  (see  Section  1.3.3  [CHOOSE  ONE],  page  5). 


1.3.5  DATE 

Usage 

(<name>  DATE  <storage>) 

Internal  Representation 

Seconds  since  1970  ("unix"  time). 

Description 

A  date.  The  user  specifies  the  month,  day,  and  year. 


1.3.6  DRAW_AREA 

Usage 

(<naae>  DRAW.AREA  <8torag«>) 

Internal  Representation 
An  X  widget 

Description 

A  drawing  area  widget  is  returned  in  the  storage  area. 


1.3.7  DISTANCE 


Usage 


(<name>  DISTANCE  <8torage>) 
Internal  Representation 
Meters. 
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Description 

A  distance.  The  user  can  specify  distance  in  meters,  kilometers,  feet,  miles,  or  nautical 
miles.  It  can  also  be  specified  by  dragging  on  the  map. 


1.3.8  FUEL 


Usage 


(<naBe>  FUEL  <8torag«>  C<raquisite>]) 


Internal  Representation 
Liters. 


Description 

A  quantity  of  fuel.  The  user  can  specify  liters,  gallons,  or  pounds.  If  a  requisite  is 
specified,  the  Fuel  display  will  only  appear  if  that  structure  member  has  a  value. 


1.3.9  LABEL 


Usage 


(<name>  LABEL  <8torage>) 

Internal  Representation 

A  NULL-terminated  string. 

Description 

An  output-only  string.  This  provides  a  facility  for  editors  to  provide  descriptive  text 
to  the  user. 


1.3.10  LINE 


Usage 


C<naBe>  LINE  <value  storage>  <length  storage>) 

Internal  Representation 

Array  of  PointOescriptions. 

Description 

A  multi-segment  line.  The  user  clicks  out  a  line  on  the  map,  and  can  edit  it  in  a  variety 
of  ways.  The  points  are  placed  in  successive  slots  of  the  <value  8torage>  array  (which 
must  be  declared  type  PointOescription).  The  number  of  points  is  placed  in  the 
<leiigth  8torage>. 
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1.3.11  MUNITIONS 


Usage 


(<naae>  MUNITIONS  <8torage>  [<requisite>] ) 


Internal  Representation 

Array  of  M\mitionQuantiti«8s. 

Description 

A  list  of  munitions.  The  user  may  change  the  value  associated  with  each  munition, 
but  not  the  type.  A  U  is  entered  for  unlimited  supplies.  When  a  U  is  entered,  the 
internal  representation  becomes  the  negative  of  the  current  value.  The  last  current  value 
becomes  the  amount  of  the  munition,  but  the  negative  sigi  des  it  is  never  decremented. 
The  munitions  are  placed  in  successive  slots  of  the  <8t^  ■■'aga>  array  (which  must  be 
declared  type  KunitionQuantity).  Unused  slots  use  the  invalid  munition  code  0.  If  a 
requisite  is  specified,  the  Munition  display  will  only  appear  if  that  structure  member 
has  a  value. 


1.3.12  OBJECT 

Usage 

«name>  OBJECT  <8torage>  [ONESHOT I  NOCANCEL]  [POINTSTYLE  <8tyle>] 
■CobjectClass. . .}) 

Internal  Representation 
ObjectID. 

Description 

A  persistent  object.  The  user  may  select  any  object  on  the  map  which  is  in  one 
of  the  specified  classes.  If  no  object  is  chosen,  the  value  0/0/0  will  be  stored.  If 
ONESHOT  is  specified,  the  value  will  be  set  back  to  0/0/0  immediately  after  the  render 
function  is  called  (this  allows  an  editor  to  pick  many  objects,  which  the  application 
then  keeps  track  of).  If  either  ONESHOT  or  NOCANCEL  is  specified,  no  Cancel  Choice 
button  will  be  provided.  If  POINTSTYLE  is  specified,  then  the  next  value  should  be  the 
type  of  point  which  is  created  by  the  system  in  response  to  a  user  map  click  (provided 
objectClassPoint  appears  in  the  list  of  classes.  The  <8torage>  must  be  an  array  of 
three  intlGs. 


1.3.13  OVERLAY 


Usage 
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(<naB«>  OVERLAY  <8torag«>) 

Internal  Representation 
ObjectID. 

Description 

An  overlay.  The  user  may  select  an  existing  overlay,  or  create  a  new  one.  Attributes 
of  the  overlay  may  also  be  edited.  If  no  overlays  e.xist  when  the  editor  comes  up,  one 
is  created.  The  <storag«>  must  be  an  array  of  three  intl6s. 


1.3.14  OVERLAY J5ISPLAY 

Usage 

(<naffl«>  OVERLAY. DISPLAY  cvalua  8torage>  <l8ngth  8torage>  SHOWIHIDE) 
Internal  Representation 

Array  of  ObjectIDs  of  overlays  that  are  selected,  and  the  number  of  elements  of  that 
array  which  are  used. 

Description 

A  choice  of  several  overlays  selected  from  a  list  of  overlays.  The  editable  can  be  config¬ 
ured  such  that  all  choices  are  presented  (SHOW),  or  with  only  the  current  choice  shown 
(HIDE).  The  objectIDs  of  all  the  selected  overlays  are  placed  in  successive  positions  in 
the  <valu«  8torag«>  array.  The  <valu«  8torag8>  array  must  be  declared  as  an  array 
of  ObjectIDs.  The  number  of  items  chosen  is  placed  in  <length  storage>. 


1.3.15  PLACE 


Usage 


(<naine>  PLACE  <storaga>) 

In  tern  al  Represen  tation 

Two-dimensional  TCC  location  (cither  two  integer,  or  two  floating  point  numbers). 

Description 

A  place.  The  user  may  i>pc  a  location  in  X/Y,  Latitude/Longitude,  or  UTM  coordi¬ 
nates,  or  may  select  a  lor.iiion  on  the  map.  The  <8torage>  must  be  an  array  of  at 
least  two  elements. 


1.3.16  SCALE 
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Usage 


(<nama>  SCALE  <8torag«>  CSKOUlHIDE]  C<min  labal>  <maz  labal> 
[<min  val>  <max  val>  C<\mit8>]]]) 


Internal  Representation 
Number. 


Description 

A  number.  The  editable  can  be  configured  such  that  the  current  value  is  shown  numer¬ 
ically  and  graphically  (SHOW),  or  only  graphically  (HIDE).  The  user  can  adjust  the  value 
by  moving  an  indicator,  or  (if  SHOW)  by  typing  a  value  (much  like  the  ANGLE  widget). 
The  minimum  and  maximum  ends  of  the  scale  are  labeled  with  the  <min  lab«l>  and 
<max  lab«l>  strings,  if  specified.  The  scale  defaults  to  a  range  of  0.0  to  1.0,  un¬ 
less  a  different  <min  val>  and  <max  val>  are  specified  (these  should  be  floating  point 
numbers).  Finally,  for  scales  configured  to  SHOW  their  value,  if  a  string  is  specified  for 
<unit8>  (such  as  "X"  or  "deg/sac"),  this  will  be  displayed  to  the  right  of  the  value. 


1.3.17  SORT 


Usage 

(<naat«>  SORT  <valu«  8torag«>  <l8iigth  8torag8>  [<oiiiit  8torage>] 

{  (<choic8  naD«>  <choic«  valu«>)  } 

) 

Internal  Representation 

Array  of  integer  or  floating  point  values  in  sorted  order,  the  number  of  elements  of  that 
array  which  are  used,  and  (optionally)  the  index  of  the  first  element  which  is  to  be 
omitted. 

Description 

A  sorted  list.  The  user  is  presented  with  a  list  o'  hoiv  as  and  may  move  them  up  or 
down  relative  to  one  another.  If  an  <omit  storage^  provided,  an  omit  line  will  be 
presented  which  may  be  exploited  by  the  user  to  indicate  that  some  choices  are  to  be 
omitted  (whatever  that  might  mean  to  an  application). 


1.3.18  SPEED 


Usage 


(<name>  SPEED  <8torage>) 

Internal  Representation 

Meters/Second. 
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Description 

A  speed.  The  user  may  specify  a  value  in  meters/second,  km/hour,  feet/second, 
miles/hour,  knots  or  mach. 


1.3.19  STEALTH 

Usage 

(<na&a>  STEALTH  <8torage>) 

Internal  Representation 
Vehicle  ID. 

Description 

A  stealth  or  stealth  preview.  The  user  may  select  a  stealth  from  the  map.  If  no  object 
is  chosen,  the  value  0  will  be  stored.  The  <8torag«>  must  be  an  int32. 


1.3.20  STRING 


Usage 


(<naiB«>  STRING  <valu«  8torag«>  <lin«8>  [<length  8torag8>]) 

Internal  Representation 

A  NULL-terminated  string. 

Description 

A  string.  The  user  may  type  up  to  the  number  of  characters  which  will  fit  in  the  passed 
<value  8torag«>  (which  must  be  an  array),  leaving  at  least  one  element  for  NULL 
termination.  The  <lines>  attribute  indicates  how  many  lines  should  be  presented  for 
text  entry  (multi-line  text  windows  are  scrollable).  If  specified,  the  <length  8torage> 
will  be  filled  with  the  length  of  the  string,  including  the  NULL  terminator. 


1.3.21  TIME 


Usage 


(<name>  TIME  <8torage>} 


Internal  Representation 
Seconds. 
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Description 

An  absolute  or  relative  time.  The  user  may  specify  a  time  with  up  to  second  resolution. 
It  is  up  to  the  application  to  decide  whether  to  treat  this  time  as  a  relative  or  absolute 
quantity. 


1.3.22  TOGGLE 

Usagp 

(<naBe>  TOGGLE  <8torage>) 

Internal  Representation 
0  or  -1 

Description 

A  True  or  False  value.  The  user  is  given  a  toggle  button  which  can  be  set  on  or  off. 


1.3.23  VECTOR 

Usage 

(<naBe>  VECTOR  <8torage>) 

Litemai  Representation 

Two  two-dimensional  TCC  locations  (either  four  integers,  or  four  floating  point  num¬ 
bers). 

Description 

A  map  click-and-drag.  The  user  clicks  on  the  map  for  the  first  location  and  drags  out 
to  the  second  location.  This  is  provided  to  facilitate  building  tools  which  use  such 
gestures  as  their  input. 


1.3.24  VEHICLE 

Usage 

(<name>  VEHICLE  <8torage>) 

Internal  Representation 

Vehicle  ID.  If  storage  is  an  array  of  three  intlGs,  the  full  48  VehiclelD  will  be  stored, 
otherwise  the  32  bit  hashed  id  will  be  used. 
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Description 

A  vehicle.  The  user  may  select  a  vehicle  from  the  map.  If  no  object  is  chosen,  the  value 
0  will  be  stored.  The  <storag«>  must  be  an  int32. 


1.4  Initialization  Rules 

Each  field  in  the  struct  part  of  the  editor  must  be  initialized.  For  example; 

(initial  (foo  CONSTANT  0) 

(bar  FORCE  "You  must  provide  a  bar") 

(baz  REFERENCE  bar) 

) 

The  initialization  method  must  be  specified  as  one  of  the  following: 

CONSTANT  (<storage>  CONSTANT  ■C<values>}) 

A  constant  value. 

FUNCTTION  (<storage>  FUNCTION  <function>) 

The  system  initializes  the  value  by  calling  a  function.  The  function  names  currently 

recognized  are: 

current.date 

Gets  the  current  date.  Only  may  be  used  with  DATE  editable, 
current.tina 

Gets  the  current  time.  Only  may  be  used  with  TIME  editable. 

FORCE  (<storag«>  FORCE  <hslp  awssage>) 

Forces  the  user  to  provide  a  value.  The  help  message  is  displayed  at  the  bottom  of  the 
screen  in  a  distracting  manner. 

REFERENCE 

(<storag9>  REFERENCE  <storag«>) 

References  another  storage  location.  If  that  storage  location  is  initialized  with  FORCE, 
the  value  will  be  copied  after  the  user  has  give  the  referent  value. 


1.5  Rendering  Information 

The  last  part  of  an  editor  definition  is  the  render  list.  It  specifies  the  names  of  storage  locations 
which,  when  changed,  should  cause  the  object  to  be  redrawn  (the  application  provides  a  drawing 
function  to  libeditor  at  create  time).  For  example: 
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(render  too  bar) 

In  addition,  the  application  may  use  the  following  reserved  words  in  the  render  list: 

APPLY  Indicates  that  an  ’Apply'  button  should  be  provided  which  the  user  can  click  on  to 
trigger  a  redraw. 

REVERT  Indicates  that  an  ’Revert'  Ijutton  should  be  provided  which  the  user  can  click  on  to 
revert  to  initial  values,  and  trigger  a  redraw. 

EXPOSE  Indicates  that  the  application  needs  to  redraw  when  the  map  is  refreshed  or  exposed 
(this  would  be  true  of  anything  which  drew  directly  on  the  map  widget). 

NOINIT  Indicates  that  the  editor  should  only  be  initialized  once.  Thereafter,  the  editor  will 
resume  with  exactly  the  configuration  it  was  left  with  when  last  exited.  This  is  useful 
for  editors  which  always  opor.iie  on  a  single  set  of  data. 
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2  Usage 


The  software  library  ‘libeditor.a'  should  be  built  and  installed  in  the  directory 
‘/conmon/lib/’.  You  will  also  need  the  header  file  ‘libeditor.h’  which  should  be  installed  in  the 
directory  Vcommon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘oaks'  in 
the  libeditor  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libeditor. 


2.1  Building  Libeditor 

The  libeditor  source  files  are  found  in  the  directory  Vcommon/libsrc/libsditor’.  ‘RCS’  format 
versions  of  the  files  can  be  found  in  ‘/nls/comnon_src/libsrc/libsditor’. 

If  the  directory  ‘comnon/libarc/libeditor'  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

i  cd  common/libsrc/libeditor 
t  CO  RCS/*,v 
•  make  install 

This  should  compile  the  library  ‘libeditor. a'  and  install  it  and  the  header  file  ‘libeditor. h' 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libeditor  should  compUe 
without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libeditor 

Libeditor  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/common/lib  -leditor  [many  other  ModSAF  libraries]’.  If  your  compiler 
does  not  support ‘-L’ syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files]  /common/lib/libedi 
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Libeditor  depends  on  libcallback,  libcoordinates,  libpo,  Ubquad,  libreader,  libsafgui,  libsensitive, 
and  libtactmap. 


2.3  Examples 

The  test  program,  ‘test.c’,  and  its  data  file,  ‘test.rdr’,  give  a  complete  example  of  how  to 
define  editors.  See  those  files  for  example  usage. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libeditor,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  edtJnit 


void  edt.init (directory,  raader.flags) 
char  *diractory; 
uint32  reader.f lags ; 


‘directory’ 

Specifies  directory  where  configuration  file  can  be  found 
‘reader.flags’ 

Specifies  reader  options  (see  section  ‘reader-read’  in  LibReader  Programmer’s  Manual) 

edt.init  initializes  libeditor,  causing  it  to  read  its  data  file  (‘editor. rdr’)  from  the  passed 
directory.  The  return  value  is  zero  if  the  read  succeeds,  or  one  of  the  libreader  return  values 
(READER_READ.EIU10II,  READER.F1LE_K0T-F0UND)  if  it  fails. 


3.2  edt_set-sensitive-x:las8 

void  edt.set.sensitive.classCgui,  type,  class) 

SGUI.PTR  gui; 

EDT_SE*rSITIVE_TYPE  type; 

SNSTVE.CLASS  eclass; 

‘gui’  Specifies  the  GUI 

‘tjrpe’  Specifies  which  sensitive  class  is  being  specified 
‘class’  Specifies  the  class  which  represents  that  type  for  this  GUI 

edt.set.sensitive.class  sets  the  class  structure  used  by  all  editors  to  interact  with  a  class 
of  senstitive  objects.  This  class  should  be  initialized  by  the  caller  with  SNSTVE.INIT.CLASS  (see 
section  ‘Class  Definition’  in  LibSensitive  Programmer’s  Manual). 
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Since  many  dh,  „.ent  libraries  define  objects  which  editors  are  interested  in.  and  since  most  of 
those  libraries  will  themselves  depend  on  libeditor,  it  makes  the  most  sense  to  have  this  information 
set  globally,  from  the  top-down.  In  cases  where  no  sensitive  class  information  has  been  given  for  a 
particular  class,  the  editors  will  merely  not  support  map  interaction  with  those  objects. 

The  type  should  be  one  of  the  following: 

Terrain  Classes 

EDT.ROADS 

Persistent  object  classes 

(Note  that  user.data  should  point  to  ALLOCd  ObjectID  structure.) 

EDT.POINT,  EDT.LINE,  EDT.SECTOR,  EDT.TEXT,  EDT.UNIT,  EDT.TASK,  EDT.TASKFRAME 
Simulation  classes 

(Note  that  user.data  should  be  vehicle  ID) 

EDT.VEHICLE,  EDT.STEALTH 


3.3  edt.offer.default.ob ject 

void  edt.offer_default_object(gui,  obj.id) 

SGUI.PTR  gui; 

ObjectIO  •obj.id; 

‘gui’  Specifies  the  GUI 

‘obj.id'  Specifies  the  object  ID 

edt.of f er.def ault.obj  ect  offers  a  default  object  to  the  next  editor  which  is  resumed.  This 
object  will  be  accepted  if  the  editor  is  forcing  the  selection  of  an  object,  and  the  offered  object  is 
of  a  type  acceptable  for  the  OBJECT  editable. 


3.4  edt.x;reate 


EDT.EDITOR.PTR  edt.createCdef inltion.  sizeof. structure, 

render.fcn,  render.arg, 
aiit.fcn,  exit.arg,  leave.mode, 
gui,  tactfflap,  tcc,  map.erase.gc, 
sensitive,  refresh. event,  db) 
REAOER.UNION  •definition; 
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uint32 

EDT.IIENDER.FUNCTION 

ADDRESS 

EDT.EXIT.FUMCTION 

ADDRESS 

int32 

SGUI.PTR 

TACTMAP.PTR 

COORD.TCC.PTR 

GC 

SNSTVE.WIHDOW.PTR 
CALLBACK_EVENT_PTR 
PO.DATABASE 


sizaof .structure : 
render.fcn; 
render. arg; 
exit. fen; 
exit. arg; 
leave.mode; 
gui; 

tactmap ; 
tcc; 

map.erase.gc; 
sensitive; 
ref re8h.event ; 
•db; 


‘definition’ 

Specifies  the  definition  of  the  editor  in  libreader  format 
‘sizeof. structure’ 

Specifies  the  size  of  the  data  structure  which  is  edited 
‘render.fcn,  render.arg’ 

Specifies  a  function  (and  argument)  which  is  called  to  render  the  data  being  edited 
(may  be  NULL) 

‘exit. fen,  exit.arg’ 

Specifies  a  function  (and  argument)  which  is  called  when  the  editor  is  exited  (may  be 
NULL) 

‘leave.mode’ 

Specifies  whether  the  current  SGUI  mode  whould  be  exited  when  the  editor  is  exited 
‘gui’  Specifies  the  GUI 

‘tactmap’  Specifies  the  tactical  map 

‘tcc’  Specifies  the  mapping  coordinate  system 

‘map.erase.gc’ 

Specifies  the  GC  used  to  erase  things  from  the  map  (provided  by  libtactmap) 

‘sensitive’ 

Specifies  the  sensitive  window 
‘refreah.event’ 

Specifies  the  event  which  fires  when  the  map  is  refreshed 
‘db’  Specifies  the  PO  database 

edt.create  creates  an  editor.  The  design  of  the  editor  is  specified  in  the  passed  definition.  The 
software  ensures  at  create  time  that  the  data  described  in  the  definition  file  correlates  with  the 
intended  structure  by  comparing  the  sizes.  The  editor  will  load  up  with  the  initial  values  specified 
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iu  the  data  file,  but  will  remain  unmanaged  until  started  by  adt.state.  The  leave.mode  flag 
indicates  whether  the  editor  should  exit  the  passed  mode  when  the  user  clicks  ’done’  or  ’abort’. 


The  render  function  should  be  declared  as  follows: 


void  render (editor,  transient,  old.data,  new.data,  arg) 
EDT_EDITOR_PTR  editor; 
int32  transient: 

ADDRESS  old.data: 

ADDRESS  new.data; 

ADDRESS  arg; 


The  transient  flag  indicates  whether  the  rendering  is  the  result  of  a  transient  operation  (such 
as  draging  the  mouse).  Libeditor  guarantees  that  after  a  transient  operation  is  finished,  render  will 
be  called  once  more  with  the  transient  flag  set  to  FALSE.. 


The  old. data  and  new.data  are  old  and  new  versions  of  the  data  being  editing.  The  old  version 
should  be  used  to  erase  the  existing  rendition,  and  the  new  version  should  be  used  to  draw. 


The  arg  is  whatever  was  passed  to  edt.create  as  the  render.arg. 


The  exit  function  should  be  declared  as  follows: 


void  «xit.function(«ditor,  data,  arg,  status) 
EDT.EDITOR.PTR  editor; 

ADDRESS  data; 

ADDRESS  arg; 

EDT.EXIT.STATUS  status; 


The  data  is  the  final  version  of  the  data  which  was  edited.  If  the  user  clicked  ’Abort’,  this  will 
be  the  same  as  the  initial  version. 


The  arg  is  whatever  was  passed  to  edt.create  as  the  exit.arg. 

The  status  is  one  of  the  following: 

EDT.DOHE  The  user  clicked  ’Done’  or  the  user  clicked  on  the  arrow  icon  and  no  forced  choices  were 
outstanding. 

EDT.AB0RT 

The  user  clicked  ’Abort’  or  the  user  clicked  on  the  arrow  icon  and  forced  choices  were 
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outstanding. 


3.5  edt-create-defaults_editor 

EDT_EOITOR.PTR  edt.create.def aulta.editorCgui ,  ezit.fcn.  ezit.arg) 

SGUI.PTR  gui; 

EDT.EXIT.FUNCTION  ezit.fcn; 

ADDRESS  ezit.arg; 

‘gui’  Specifies  the  GUI 

‘ezit.fcn,  ezit.arg’ 

Specifies  the  function  to  call  at  exit 

edt.create.defaults.editor  creates  the  libeditor  user  preferences  (defaults)  editor.  This 
editor  allows  customization  of  default  units  for  many  editable  types. 


3.6  edt.jcreate^rofile_menu 

void  edt.create.profile.Benu(gui.  dialog_parent ,  dir) 

SGUI.PTR  gui; 

Widget  dialog.parent; 
char  dirQ ; 

‘gui’  Specifies  the  GUI 
‘dialog_parent’ 

Specifies  the  widget  which  should  parent  libxfile  dialogs 
‘dir’  Specifies  the  directory  where  profiles  are  stored 

edt.create.prof  lle.Beiiu  create  the  user  profile  menu,  which  allows  the  user  to  save/load  the 
contents  of  the  user  preferences  (defaults)  editor. 


3.7  edtJoad 

void  adt.loadCaditor,  data,  size) 
EDT.EDITOR.PTR  editor; 
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ADDRESS  data; 

uint32  size; 

‘editor’  Specifies  the  editor 

‘data’  Specifies  the  data 

‘size’  Specifies  the  size  of  the  data 

edt.load  loads  the  passed  data  into  the  editor.  If  you  pass  NULL  for  the  data,  it  reloads  the 
editor  with  the  initial  values. 


3.8  edt Joad_reader 


void  edt.load.reader (editor,  count,  data) 
EDT_EDITOR.PTR  editor; 
int32  count ; 

READER_UNION  *data: 


‘editor’  Specifies  the  editor 

‘count’  Specifies  the  number  of  initialization  parameters  (typically 
read.data. array Co] .integer  -  2) 

‘data’  Specifies  the  initialization  parameters  (typically  Aread. data. array C2]) 


edt.load.reader  loads  the  passed  libreader  format  data  into  the  editor  for  subsequent  initial¬ 
ization.  This  initialization  overrides  the  initialization  parameters  originally  ^ven  the  editor.  Fields 
which  are  not  specified  retain  their  original  initialization  methods  and  values. 


3.9  edt jset..field 


void  •dt.sat.fioldCaditor,  mafflber.offsat,  addr,  siz«) 
EDT.EDIT01l_PTR  editor; 
uint32  manb«r_offs«t; 

ADDRESS  addr; 

uint32  size; 


‘editor’  Specifies  the  editor 
‘meaber.offset’ 

Specifies  the  byte-offset  of  the  field  which  is  to  be  changed 
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‘addr’  Specifies  the  address  of  the  new  value 

‘size’  Specifies  the  size  of  the  new  value 

edt.set.field  initializes  a  single  field  of  a  running  editor,  as  though  the  user  had  specified 
that  field.  The  format  of  the  provided  value  must  the  be  same  as  the  storage  format  of  that  field 
in  the  edited  data  structure. 


3.10  edt_apply_offset 


void  edt_apply_olf8«t(«ditor.  member.of f sat .  index,  dx,  dy) 
ED1_EDIT0R.PTR  editor; 
uint32  member.of fset; 

int32  index: 

int32  dx ,  dy ; 


‘editor’  Specifies  the  editor 
‘nember.offset’ 

Specifies  the  byte-offset  of  the  field  which  is  to  be  changed 
‘index’  If  changing  a  line,  specifies  the  index  of  the  point  to  be  changed 
‘dx,  dy’  Specifies  the  amount  of  change  (in  pixels) 


•dt.apply.offeet  incorporates  the  user’s  initial  drag  into  the  currently  edited  graphic,  as 
though  the  drag  had  occurred  in  the  context  of  the  editor.  The  menber.offset  identifies  which 
member  of  the  structure  the  offset  should  bo  applied  to  (if  not  a  PLACE  or  LINE  editable,  nothing 
will  happen).  The  index  field  specifies  (for  LINEs  only)  which  vertex  should  be  offset;  -1  indicates 
movement  of  the  whole  object. 


3.11  edt_state 


void  edt.etate (editor,  aode,  state) 
EDT.EDITOR.PTR  editor; 
SGUI.MODE.PTR  mode; 
SGUI.M00E.STATE  state: 


‘editor’ 

‘iBode’ 


Specifies  the  editor 

Specifies  the  mode  w  iih  the  state  (used  for  display  of  help  messages) 
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‘state’  Specifies  the  new  state 


edt.state  sets  the  state  of  an  editor  to  one  of  the  libSAFGUI  states  (ACTIVE,  SUSPENDED. 
RESUMED,  INACTIVE). 


See  section  ‘sgui.jidd_mode’  in  LibSAFGUI  Programmer’s  Manual. 


3.12  edt_query 


int32  edt.queryCeditor.  value) 
EDr_EDITOR.PTR  editor; 
ADDRESS  value ; 


‘editor’  Specifies  the  editor 

‘value’  Returns  the  editor  values 

edt.query  gets  the  current  values  of  the  object  being  edited.  The  return  value  is  1  if  any  forced 
choices  are  still  unresolved,  0  otherwise.  This  may  be  called  when  the  editor  is  inactive. 


3.13  edt_naine 

char  ««dt.naffl«(«dltor) 
EDT_EDITOR_PTR  editor; 

‘editor’  Specifies  the  editor 

edt_iiaDe  returns  the  name  of  the  editor. 


3.14  edt_get-references 


void  edt.get.references (editor,  data,  ref count,  references) 
EDT.EDITOR.PTR  editor; 

ADDRESS  data; 

uintS  *ref count; 

Obj  ectlD  references  □ ; 
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‘editor’  Specifies  the  editor 

‘data’  Specifies  the  data  which  contains  the  references 
‘ref count’ 

Returns  the  number  of  ObjectID  references  made  by  the  editor 
‘references’ 

Returns  the  ObjectID  value  for  each  reference  made  in  the  passed  data 

edt.get.references  finds  all  the  ObjectID’s  referenced  in  the  passed  data  structure  and  copies 
them  into  the  passed  array.  This  can  be  used  to  fill  in  the  references  list  in  a  Task  Class  object. 


3.15  edt_format 


uint32  edt.formatCgul,  output,  format,  args...) 
ADDRESS  gui; 
char  output  □ : 

char  format  □ ; 

args . . . 


gui 

‘output’ 
‘format’ 
‘args . . . ’ 


Specifies  the  GUI  (declared  as  an  ADDRESS  so  libraries  needn’t  specifically  depend 
upon  libSAFGUI) 

Returns  the  formatted  string 
Specifies  the  output  format 
Specifies  format  arguments 


edt.f  ormat  is  like  sprintf ,  in  that  it  generates  a  formatted  output  based  upon  a  format  string, 
and  a  set  of  arguments.  Whereas  sprintf  uses  X  to  specify  output  tokens,  sdt.foxmat  uses  i. 
Values  are  output  in  a  manner  appropriate  given  the  user’s  GUI  preferences  (UTMs  vs  Lat/Long, 
for  example).  The  return  value  is  the  length  of  the  formatted  string.  The  recognized  tokens  are  as 
follows: 

Altitude 

Token  ih 

Argument  float64 
Units  Meters 

Example  “28000  feet" 

Angle 

Token  fa 
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Argument  float64 
Units  Radians 
Example  "35  degrees" 

Distance 

Type  9d 
Argument  float64 
Units  Meters 
Example  "150  feet" 

Fuel 

Type  #f 
Argument  float64 
Units  Liters 
Example  "2000  lbs" 

Location 

Type  il 

Argument  C00RD_TCC_PTR  float64  float64 
Units  Meters  (X,  Y) 

Exam  pie  "  16SES4500S500" 

Object 

Type  io 

Argument  PO.DATABASE  *  ObjectID  * 

Example  "Task  Frans  'Fly  On  Route*" 

Speed 

Type  ts 
Argument  float64 
Units  Meters/Second 
Example  "machl.l" 

Vehicle 

Type 

Argument  VehiclelD  * 

Example  "All  (15)" 

Also,  the  following  tokens  are  provided  to  avoid  the  need  to  use  both  edt.f  ormat  and  sprintf : 


Chapter  3:  Functions 


29 


Integer 


String 


Token 

•G 

Argument 

float64 

Same  as 

%g 

Token 

«D 

Argument 

int32 

Same  as 

Xd 

Token 

•S 

Argument 

char  * 

Same  as 

U 

3.16  edt^vd^efaults 


void  •dt.pvd.daf aulta (gui ,  result) 
SGUI.PTR  gui ; 

EDT.PVD_DEFAULTS  ereault; 


‘gui’  Specifies  the  GUI 
‘restilt’  Returns  the  settings 

edt_pvd_default8  returns  user  preferences  (defaults)  editor  choices  related  to  PVD  operation. 


3.17  edt_color_choice 


void  edt.color_choice(editor,  pretty.naffle,  value,  color) 
EDT.EDITOR_PTR  editor; 
char  *pretty_nane ; 

int32  value; 

Pixel  color; 


‘editor’  Specifies  the  editor 
‘pretty.naffle’ 

Specifies  a  libreader  symbol,  which  identifies  the  editable 
‘value’  Specifies  the  value  associated  with  the  choice  to  be  colored 
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‘color’  Specifies  the  desired  color. 

edt.color. choice  sets  the  foreground  color  of  a  button  in  a  CHOOSE.ONE  or  CHOOSE.SONE 
editable.  The  pretty.name  should  be  a  librcader  symbol  which  corresponds  to  the  name  of  the 
editable  in  the  editor  section  of  the  definition  file  (see  Section  1.3  [Editor  Definition],  page  4). 


3.18  edt_editor-empty 

int32  edt.editor.eoptyCeditor) 

EDT.EDIT0R_PTR  editor; 

‘editor’  Specifies  the  editor 

edt.editor.empty  returns  TRUE  it  the  editor  has  no  editables. 
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4  Events 

The  following  sections  describe  each  event  provided  by  libeditor. 

4.1  edt  .defaults  .callback 

CALLBACK.EVENT.PTR  edt.dafaulta. callback; 

The  edt.dafaulta. callback  event  fires  in  response  to  the  user  changing  the  settings  of  the 
defaults  editor. 

The  handler  should  be  prototyped  as  follows: 

void  handlar(gui) 

SGUI.PTR  gui; 

See  Section  3.16  [edt’pvd'defaults],  page  29. 
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5  X  Resource  Definitions 


Many  attributes  of  the  fields  which  make  up  an  editor  are  specified  via  the  X  resource  database. 
These  can  be  overridden  for  individual  fields  in  individual  editors,  to  customize  the  interface  beyond 
its  default  appearance. 

In  general,  a  resource  override  should  be  formatted  as  follows: 

♦ .  SAFGUI .  • .  Editor .  • .  Editor  Name .  * .  Field  Name.  * .  [Component  Name],  A  ttribute :  Value 

For  example,  to  change  the  label  on  the  object  button  for  the  unit  field  in  the  mission  assignment 
editor: 

♦ . SAFGUI . * . Editor .•.Mission  Assignment . * . Unit . ♦ . Ob j ectButton . labelString :  \ 

Select  Unit  from  Map 

To  change  the  help  string  associated  with  this  editable: 

•.SAFGUI.*. Editor.*. His 8 ion  Assignment. •.Unit.*. Help:  \ 

Select  a  unit  from  the  map  (valid  choices  are  hot). 

As  these  examples  show,  the  component  name  of  the  field  is  only  needed  when  the  resource 
would  otherwise  be  ambiguous  (it  is  needed  for  the  first  example  because  both  the  Ob  j  ectButton 
and  the  Cancel  Choice  members  have  a  labelstring  attribute). 
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6  Defining  New  Types 


One  design  goal  of  libEditor  is  that  tho  user  is  never  confronted  with  raw  data  types  (such  as 
"a  number").  It  is  much  better  if  the  input  is  requested  in  a  way  specifically  designed  for  the 
parameter  being  specified  (such  as  "a  .speed").  It  seems  likely  that  as  the  program  expands,  we 
will  find  continue  to  find  more  types  of  (juantities  that  can  be  edited.  This  chapter  give  step  by 
step  instructions  for  adding  a  new  type. 

Note  that  it  if  you  choose  to  use  a  liuilt-in  Motif  widget  class  (such  as  xmToggleButtonWid- 
getClass),  you  must  call  the  function  •dt.focus.fiz  on  the  created  widget.  This  is  to  correct  a 
problem  with  Motif  focus  management  (clicking  in  a  widget  which  already  has  the  focus  pushes  the 
focus  into  an  adjacent  widget).  Custom  widgets  (such  as  the  edt_date\VidgetClass)  do  not  need 
this  function  called  on  them  at  create  time,  because  they  explicitly  prevent  the  problem  in  their 
implementation  using  a  construct  like: 

if  (I.XoFocualsHereC (Widget) «)) 

XniProcessTraversaK  (Widget) w,  XniTRA VERSE. CURRENT)  ; 

in  their  focus-accepting  methods. 

The  procedure  described  is  relatively  simple,  since  it  does  not  require  map  input,  a  unique  input 
widget  (it  is  assembled  from  text  &  toggles),  or  any  special  map  display  methods.  To  create  a 
widget  with  these  features,  first  follow  the  instructions  below,  then  find  another  editable  (such  as 
PLACE  or  ANGLE)  to  use  as  an  example  for  the  other  features. 

1.  Name  the  t3rpe.  Choose  a  name  which  is  short  and  descriptive. 

2.  Add  the  necessary  t}rpes  and  prototypes  to  *lib«dt_local.h’.  Each  widget  type  has  its  own 
section  in  this  file,  add  the  new  one  Just  before  the  comment: 

/*  ADD  NEW  TYPES  HERE  •/ 

3.  Define  any  necessary  enumerated  typos  and  prototype  the  create  and  set.value  functions. 

4.  If  the  editable  supports  different  units,  add  them  to  the  EDT.DEF AULTS  data  structure. 

5.  Add  the  name  of  the  new  type  to  the  EOT.CLASS  enumerated  type  (put  it  in  alphabetical 
order). 

6.  If  the  editable  will  support  anv  sixTial  configuration  parameters  (display  options,  etc.),  create 
a  EI}T_<cla88> .CONFIG  structure  to  hold  them,  just  prior  to  the  comment: 

/*  ADD  NEW  CONFIGS  HERE  •/ 

Then  add  that  to  the  conf  ig  hi'miiImt  of  the  EDT.EDITABLE  structure. 
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7.  Update  the  file  ‘editor. rdr’  to  include  the  new  units.  Be  sure  to  add  the  new  field  to  tlie 
struct,  editor,  initial  and  render  lists. 

8.  Update  the  functions  save.profile  and  losd_profile  in  ‘edt_profile.c’  to  include  the 
new  units. 

9.  Next,  add  co'^e  to  ‘edt.init.c’  to  recognize  and  create  the  new  type.  Find  the  comment: 

/*  ADD  NEW  SYMBOLS  HERE  */ 

and  add  a  variable  to  the  list  (in  alphabetical  order)  for  the  new  type.  Add  the  initialization 
for  that  type,  just  below.  FinaUy,  add  the  new  type  to  the  if-els«-if  chain  a  little  farther 
down. 

10.  If  the  editable  requires  a  certain  type  of  storage  (must  be  an  integer,  for  example),  add  a  check 
for  that  before  the  comment: 

/*  add  new  checks  here  */ 

11.  If  the  editable  supports  special  configuration,  add  the  necessary  parsing  before  the  comment: 

/*  ADD  NEW  CONFIG  PARSING  HERE  */ 

12.  Add  a  case  to  the  switch  in  the  function  creatw.widgwt  to  create  the  new  widget  type.  Put 
it  in  alphabetical  order. 

13.  Next,  add  code  to  ‘wdt.state.c’  to  initialize  the  new  type.  Find  the  comment: 

/*  ADD  NEW  INITIALIZAnON  HERE  */ 

and  add  a  casa  to  the  switch  to  initialize  the  new  type.  Note  that  at  this  point  the  values  have 
already  been  converted  into  every  necessary  format,  so  just  use  the  one  which  is  appropriate 
for  the  new  editable. 

14.  Create  a  file  in  which  to  define  the  new  widget  ‘•dt_<typa> .  c’.  This  is  fairly  easy  if  you  start 
with  a  similar  widget  definition  file  as  a  prototype,  and  use  case-insenstive  string  replace  to 
customize  it. 

15.  Add  necessary  resources  for  this  new  widget  to  ‘editor. zrdb’.  This  should  include  a  help 
string,  and  probably  some  layout  information  (again,  find  a  similar  widget  and  copy  it). 

16.  Add  a  description  of  the  new  editable  type  to  the  Editor  Definition  section  of 
‘libeditor .  texinf  o’. 

17.  Add  the  new  file  to  the  ‘Makefile’. 

18.  Test  the  new  editable  by  adding  it  to  the  test  editor  defined  in  ‘test.rdr’  and  ‘test.c’. 
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1  Overview 


Libentity  provides  a  uniform  interface  to  all  network  entities  represented  within  SAF.  Entity  is 
a  sub-class  of  each  vehicle. 


In  addition  to  the  bookkeeping  functions  to  create,  destroy,  activate,  etc.,  libentity  provides  a 
collection  of  get  and  set  functions  for  each  of  the  entity  state  variables.  This  functions  act  as  a  lazy 
evaluation  buffer,  which  prevents  conversions  to  or  from  network  representation  until  absolutely 
necessary,  and  then  saves  those  converted  values  until  they  once  again  become  out  of  date. 

Note  that  libentity  currently  only  supports  getting  DIS  style  data  from  an  entity.  In  the  future, 
libentity  may  be  modified  to  accept  the  setting  of  DIS  style  data  for  local  vehicles,  causing  SIMNET 
style  data  to  be  derived  from  the  DIS  data. 


The  entity  sub-class  of  the  vehicle  is  also  responsible  for  maintaining  that  vehicle’s  location  in 
the  position-based  table.  For  local  vehicles,  this  update  occurs  whenever  the  position  is  changed. 
For  remotes,  this  update  occurs  either  (1)  when  a  packet  is  received  which  modifies  the  remote 
vehicle’s  position,  or  (2)  when  the  RVA’d  position  of  the  vehicle  exceeds  a  tolerable  error  threshold 
from  the  position  represented  in  the  table. 

Lazy  evaluation  of  remote  vehicle  RVA  is  implemented  to  guarantee  the  following: 

•  Each  remote  vehicle  is  RVA’d  no  more  often  than  once  every  full  loop  through  the  scheduler. 

•  Remotes  are  not  RVA’d  unless  get.position  is  explicitly  called,  or  RVA  is  necessary  to  update 
the  position-based  vehicle  table. 


The  parameters  for  an  entity  are  used  primarily  for  network  interactions.  They  are  as  follows: 


(SH.Entity  (leiigth.tlir«8hold  <r«al  p«rc«nt>) 

(vidth.threahold  <real  perc«nt>) 

(height.threshold  <real  p«rc«nt>) 

(rotation.thr«8hold  <r«al  degr««8>) 

(tuxret.throahold  <r8al  aziamth  d8gr888>) 

(g;un.thre8hold  <real  elevation  degree8>) 

(vehicle_cla88  <int  cla88>) 

(guiaea  <int  primary  gui8e>  ;;  What  thia  thing  really  ia 
<int  secondary  gui8e>  ;;  A  aimilary  thing  vith  an 

opposite  country  code 
(8end_di8_deactivate  <true  I  fal8e>} 

) 
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) 

The  thresholds  are  used  for  dead  reckoning,  to  indicate  when  a  packet  should  be  transmitted. 
They  are  typically  10%  and  3  degrees.  The  vehicle.class  should  be  either  vehicleClassSimple 
or  vehiclaClassTank,  depending  upon  whether  the  vehicle  has  a  turret.  Two  guises  must  be  pro¬ 
vided  -  the  primary  guise,  which  should  be  accurate;  and  the  secondary  guise  which  should  be  a  simi¬ 
lar  vehicle  with  a  different  country  code  ( used  in  relative  battle  scheme  battles),  send.dis.deactivate 
is  a  boolean  value  indicating  whether  or  not  the  entity  should  send  a  DIS.DEACTIVATE.REQUEST 
pdu  when  the  entity  deactivates  (under  DIS).  This  will  typcially  be  true  for  all  vehicles  except 
missiles,  since  missile  impacts  provide  an  implicit  deactivate  under  DIS. 
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2  Examples 


To  set  an  entity’s  position: 


iinclude  <libentity.h> 
float64  pos; 

ent.set.positionC vehicle. id.  pos) ; 


To  get  an  entity’s  position: 


iinclude  <libentity.h> 

•  •  • 

float64  pos; 

ent.get.positionCvehicle.id,  pos) ; 

To  get  an  entity’s  position  and  velocity  via  Ubaccess: 


iinclude  <libaece88.h> 

iinclude  <libentity.h>  /•  To  get  key  prototype  */ 
iinclude  <8tdezt.h>  /•  To  get  A.END  */ 

•  •  • 

f loat64  po8 [3] ; 
float64  vel[3]; 

acce88_get(vehicle_id, 

ent.poaition,  poa, 
ent_ velocity,  vel, 

A_END); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libentity,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  entJnit 

void  ent.initC packet. valve,  tcc,  protocol,  use.atlas. variations) 

PV.VALVE.PTR  packet.valve; 

COORD.TCC.PTR  tcc; 

int32  protocol ; 

int32  use.atlas.Mariations; 

‘packet.valve’ 

Specifies  the  packet.valve  to  use  when  sending  packets. 

‘tcc’  Specifies  the  terrain  coordinate  system 

‘protocol’ 

Specifies  protocol  in  use  (0  for  SIMNET,  DIS.PROTOCOL.VERSIOH.*  for  DIS) 
‘use.atlas.variations’ 

Specifies  whether  to  use  the  Atlas  Elektronik  protocol  variations  when  communicating 
with  a  DIS  protocol.  This  impacts  conversions  of  locations  and  velocities. 


ent.init  initializes  libentity.  Call  this  before  calling  any  other  libentity  functions.  The 
packet.valve  is  created  with  a  call  to  pv.create. valve. 


3.2  ent jset jninimum-pbt_error 

void  ent.8et.iiiiniiituiB.pbt.error(error. threshold) 
float64  error. threshold; 

‘error. threshold’ 

Specifies  the  maximum  error  allowed  between  a  vehicle’s  actual  location  and  that  used 
in  the  position-based  table. 

ent.set.minimuffl.pbt.error  reduces  the  allowable  error  (in  meters)  in  the  position- based  table. 
Only  those  remote  vehicles  which  exceed  this  error  will  be  RVA’d  and  updated  in  the  position  based 
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table.  Calls  which  pass  larger  values  than  the  current  threshold  are  ignored.  Until  this  error  value 
is  set,  no  RVA  will  be  done  on  behalf  of  the  position-based  table  (RVA  will  be  done,  however,  for 
those  vehicles  which  have  their  position  queried). 


3.3  ent_get_minimum_pbt_error 
float64  ent_get_minimum_pbt_error() 

ent_get_miniffluiii_pbt.error  returns  the  current  error  threshold  being  maintained  by  libentity 
for  the  position-based  table. 

See  (undefined)  [ent'set'minlmum'pbt 'error],  page  (undefined). 


3.4  ent.jsetJbattle_scheme 

void  ent.8et.battl«_8ch«me(battle_8cheaa) 
uintS  battle_8ch«m8 : 

’battle.8cheffle’ 

Specifies  the  new  battle  scheme  (battleSchemcRalative  or  battleSchaneAbsolute). 

ent_8et  .battle_8ch«m8  sets  the  battle  scheme  used  to  generate  vehicle  guises  for  local  vehicles. 
The  PARAMETRIC.DATA  used  by  an  entity  specifies  two  guises  which  are  used  to  describe  the  vehicle, 
one  which  actually  represents  the  vehicle,  and  a  similar  one  on  the  other  side.  For  example,  a 
T72-M  tank  might  be  defined  with  the  guises: 

(gui888  V8hicl8.USSIl.T72N  V8hicl8.US.Hl) 
or, 

(gui888  V8hicl8.USSILT72M  v8hicl8.G8Tinany.LE02) 

The  relationship  cf  this  data  to  what  goes  out  on  the  network  is  a  function  of  both  the  global 
battle  scheme  and  the  force  of  the  ^ven  vehicle.  The  rules  are  as  follows: 


•  For  relative  battle  scheme,  if  the  force  is: 
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distinguished,  other 

The  guises  are  used  just  as  they  appear  in  the  PARAMETRIC. DATA, 
observer  A  US  or  German  object  type  is  selected  for  both  guises, 
target  A  USSR  object  type  is  selected  for  both  guises. 

•  For  absolute  battle  scheme,  if  the  force  is: 
distinguished,  other 

The  first  guise  listed  in  the  PARAMETRIC.DATA  is  used  for  both  guises. 

observer  A  US  or  German  object  type  is  selected  for  the  distinguished  guise,  and  a  USSR 
object  type  is  selected  for  the  other. 

target  A  USSR  object  type  is  selected  for  the  distinguished  guise,  and  a  US  or  German 
object  type  is  selected  for  the  other. 


3.5  ent.£lass Jnit 

void  ent.class.initCparent.class) 

CLASS.PTR  parent.class ; 

‘parent.class’ 

Specifies  the  parent  class  of  entity  (probably  safobjxlass). 

ent .class. init  creates  a  handle  for  attaching  Entity  class  information  to  vehicles.  The 
parent.class  is  one  created  with  class.declare.class. 


3.6  ent.jcreate 


void  ent.createCvehicle.id,  panns,  deactivate.fcn) 
int32  vehicle.id; 

ENTITY.PARAMETRIC.DATA  oparns; 

void  (edeactivate.f cn) (/*  int32  vehicle.id  */) ; 


'vehicle.id' 

Specifies  the  vehicleJd  of  the  vehicle  to  be  created. 

‘panns’  Specifies  parametric  data  for  the  entity. 

‘deactivate.fcn’ 

Specifies  the  function  to  call  if  the  remote  vehicle  is  deactivated. 
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•nt.creat*  creates  the  Entity  class  information  for  a  vehicle  and  attaches  it  to  the  vehicle’s 
libclass  user  data.  All  vehicle  start  inactive.  Local  vehicles  become  active  (start  broadcasting 
appearance  packets)  when  ent^activate  is  called.  Remote  vehicles  become  active  when  their  first 
appearance  packet  is  received.  The  argument  ’parms’  is  only  necessary  for  local  vehicles.  You  may 
pass  NULL  for  this  argument  for  remotes. 

The  deactivateJcn  is  called  when  remote  vehicles  receive  a  deactivate  request  packet.  It  is  up 
to  the  creator  of  the  instance  to  act  on  the  deactivate. 

Libentity  keeps  a  five  minute  history  of  vehicles  which  it  has  deactivated  (for  whatever  reason). 
When  ent.create  is  called  with  a  vehicle. id  which  corresponds  to  a  vehicle  in  this  history,  the 
new  vehicle  is  automatically  initialized  with  the  values  from  the  previous  incarnation.  The  position 
is  RVA’d  forward  to  where  the  vehicle  would  be  at  the  current  time,  had  it  not  ceased  to  exist.  This 
functionality  is  provided  to  simplify  simulation  handoif.  In  other  cases,  the  caller  would  normally 
set  all  the  fields  of  the  entity  appearance  to  override  these  default  values. 

This  can  be  called  for  Any  vehicle. 


3.7  ent.jdestroy 

void  ent.d«8troy(v«hicle_id) 
int32  vehicle. id; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 


ent.destroy  frees  the  Entity  class  information  for  a  vehicle.  For  local  active  vehicles,  a  deac¬ 
tivate  will  automatically  be  sent. 

This  can  be  called  for  Any  vehicle. 


3.8  ent_tick 


void  ent.tickCvehicle.id) 
int32  vehicle.id: 
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‘vehicle. id’ 

Specifies  the  vehicle  ID. 

ent.tick  for  remotes,  manages  timeouts  and  RVA.  For  locals,  sends  current  appearance  of 
vehicle  on  network  if  warranted  by  RVA  thresholding.  This  should  be  called  no  more  often  than 
once  per  67ms. 

This  can  be  called  for  Any  vehicle. 


3.9  ent^acket.received 

void  ent.packet.receivedCvehicle.id,  packet) 
int32  vehicle. id; 

PV.PACKET  •packet; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘packet’  Pointer  to  the  packet  received. 

ent.packet.received  calls  this  function  when  a  new  appearance  packet  or  a  deactivate  packet 
is  received  off  the  network.  The  packet  must  be  allocated  using  pv.buffer.allocate. 

Receipt  of  an  appearance  packet  will  cause  the  update  of  the  position-based  table  component 
of  the  vehicle. 

This  can  be  called  for  Remote  vehicles  only. 


3.10  ent jsetuexercise Jd 


void  ent.set.ezercise.idCvehicle.id,  ezercise.id) 
int32  vehicle.id; 
uintS  ezercise.id; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 


10 


LibEntity  Programmer’s  Guide 


‘exercise.id’ 

Specifies  the  exercise  ID. 

ent.set.axercise.id  sets  the  exerciseJd  field  of  the  entity.  This  may  be  called  more  than 
once  (to  change  exercises,  for  example). 

This  can  be  called  for  Local  vehicles  only. 


3.11  ent_Activate 

void  ent.activataCvahicla.id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

ent.activate  allows  appearance  packets  to  be  sent  on  the  network  for  this  vehicle. 
This  can  be  called  for  Local  vehicles  only. 


3.12  ent_deactivate 


void  ent.deactivateCvehicle.id,  reason) 
int32  vehicle.id; 

DeactivateReason  reason; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

ent.deactivate  prohibits  transmission  of  appearance  packets  for  this  vehicle.  It  will  send  a 
deactivate  packet  if  the  vehicle  is  not  already  inactive.  The  sent  deactivate  packet  will  be  marked 
with  the  supplied  DeactivateReason. 


This  can  be  called  for  Local  vehicles  only. 


Chapter  3;  Functions 


11 


3.13  ent^ctive 


int32  ent.activeC vehicle. id) 
int32  vehicle.id; 


‘vehicle. id' 

Specifies  the  vehicle  ID. 

ent.active  returns  whether  the  vehicle  is  currently  active  (see  (undefined)  [ent ’activate],  page  (un¬ 
defined)). 

This  can  be  called  for  Any  vehicle. 


3.14  ent_clear_thresh_stats 


void  ent. clear. thresh.stats() 


ent.clear.thresh.8tats  resets  all  thresholding  statistics  to  zero. 


See  (undefined)  [ent’print’thresh'stats],  page  (undefined). 


3.15  ent^rint_thresh.jBtats 


void  ent.print.thresh.8tat8() 


ent.print.thra8h.8tat8  prints  RVA  thresholding  statistics. 


3.16  ent.jconvertJocation-to.dis 


void  ent.convert.location.to.di8 (vehicle.id,  inteznal.location,  dia.location) 
int32  vehicle.id; 

float64  eintemal.location; 

float64  *di8. location; 
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‘vehicle.ld’ 

Specifies  the  vehicle  ID  (or  0  if  none  available) 

‘internal.location’ 

Specifies  a  location  in  the  internal  format  (TCC) 

'dis.location’ 

Returns  the  same  location  in  the  DIS  format  (GCC  or  Atlas,  depending  upon  how 
libentity  was  initialized) 

•nt_conv«rt.location_to_dls  converts  the  passed  location  from  internal  to  the  DIS  format. 
This  is  provided  as  a  convenience  so  libraries  do  not  all  have  to  hold  on  to  the  TCC. 


3.17  ent_convert.velocity_to_dis 


void  •nt.convort.valocity.to.disCvehiclo.id,  intarnal. velocity, 

intomal.location,  dis. velocity) 

int32  vehicle.id; 

float64  vinternal. velocity: 

float64  vinternal.location; 

float32  vdis.velocity; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘internal.velocity’ 

Specifies  a  velocity  in  the  internal  format  (TCC) 

‘internal.location’ 

Specifies  a  location  in  the  internal  format  (TCC)  (pass  a  NULL  pointer  if  none  is 
known) 

‘dis.velocity’ 

Returns  the  same  velocity  in  the  DIS  format  (GCC  or  Atlas,  depending  upon  how 
libentity  was  initialized) 


ent.convert. velocity. to.die  converts  the  passed  velocity  from  internal  to  the  DIS  format. 
This  is  provided  as  a  convenience  so  libraries  do  not  all  have  to  hold  on  the  transformation  matrices. 
NOTE:  the  dis.velocity  is  returned  as  float32  *,  since  that  is  how  it  is  stored  in  DIS  packets. 


3.18  ent.convert Jocation J’rom.xlis 
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void  •nt.convert.location.froD.disC vehicle. id, 

dia.location,  intemal.location) 

int32  vehicle.id; 

float64  vdis.location: 

float64  * internal. location: 

‘vehicle.id’ 

Specifies  the  vehicle  ID  (or  0  if  none  available) 

‘dia.location’ 

Specifies  a  location  in  the  OIS  format  (GCC  or  Atlas,  depending  upon  how  libentity 
was  initialized) 

‘intemal.location’ 

Returns  the  same  location  in  the  internal  format  (TCC) 

ant.convert.location.from.dia  converts  the  passed  location  from  DIS  to  the  internal  format. 
This  is  provided  as  a  convenience  so  libraries  do  not  all  have  to  hold  on  to  the  TCC. 


3.19  ent.jconvert_velocity J'rom -dis 

void  ent.convert.velocity.from.dia(vehicle.id,  dia.velocity, 

internal. velocity ,  intemal.location) 

int32  vehicle.id: 

float32  *di8. velocity; 

float64  vintamal. velocity; 

float64  eintomal.location; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘dia.velocity’ 

Specifies  a  velocity  in  the  DIS  format  (GCC  or  Atlas,  depending  upon  how  libentity 
was  initialized) 

‘intemal.velocity’ 

Returns  the  same  velocity  in  tlio  internal  format  (TCC) 

‘intemal.location’ 

Specifies  a  location  in  (In'  int<*rnal  format  (TCC)  (pass  a  NULL  pointer  if  none  known) 

ent.convert.velocity.fron.dis  <  •inv<>rt!i  the  passed  velocity  from  DIS  to  the  internal  format. 
This  is  provided  as  a  convenient'*'  '•>  libr.irK's  <io  not  all  have  to  hold  on  the  transformation  matrices. 
NOTE:  the  dia.velocity  is  .f  fl3at32  •.  since  that  is  how  it  is  stored  in  DIS  packets. 
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3.20  ent_format Jocation 


char  *ent_forDat_location(vehicle.id.  x.  y) 
int32  vehicle. id; 

float64  X,  y; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘x,  y’  Specifies  the  location 

*nt.fomat_location  converts  the  passed  location  to  a  character  string  suitable  for  transmis¬ 
sion  in  a  radio  message.  Currently  this  will  be  as  a  UTM  string,  but  in  the  future  the  output 
format  may  become  a  parameter  of  the  entity. 


3.21  ent.set_vehicle_class 


void  •nt.set.vahicle.clast (vehicle.id,  vehicle.claee) 
int32  vehicle.id; 

VehicleClaee  vehlcle.clase ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘vehicle.clasa’ 

Specifies  the  new  class  (Static,  Simple,  Tank). 

ent.set.vehicle.claas  is  used  to  set  the  vehiclejclass  attribute  of  vehicle  appearance.  This 
attribute  is  not  translated  to  network  representations  until  absolutely  necessary. 

This  can  be  called  for  Local  vehicles  only. 


3.22  ent.net.force Jd 


void  ent.aet.force.idCvehicle.id,  force.id) 
int32  vehicle. id ; 

ForcelD  force.id; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘force. id’ 

Specifies  the  new  force  (distinguished,  other,  observer,  target). 

ent.set.force.id  is  used  to  set  the  forceJd  attribute  of  vehicle  appearance.  This  attribute  is 
not  translated  to  network  representations  until  absolutely  necessary. 

This  can  be  called  for  Local  vehicles  only. 


3.23  ent.set...guise8 


void  ent.set.guisesCvehicle.id,  guises) 
int32  vehicle. id; 

VehicleGuises  *guises; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘guises’  Specifies  the  new  guises. 


ent.set.guises  is  used  to  set  the  guises  attribute  of  vehicle  appearance.  This  attribute  is  not 
translated  to  network  representations  until  absolutely  necessary. 


This  can  be  called  for  Local  vehicles  only. 


3.24  ent.set jfnarking 


void  ent.8st_marking( vehicle. id,  marking) 
int32  vehicle. id ; 

VehicleMarking  *marking: 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘marking’  Specifies  the  new  marking. 
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ent.sat.marking  is  used  to  set  the  marking  attribute  of  vehicle  appearance.  This  attribute  is 
not  translated  to  network  representations  until  absolutely  necessary. 


This  can  be  called  for  Local  vehicles  only. 


3.25  ent jset_position 


void  ent_set_position(v«hicle_id,  position) 
int32  vehicle .id; 

float64  position [3] ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

^position' 

Specifies  the  new  position. 


ent.set.position  is  used  to  set  the  position  attribute  of  vehicle  appearance.  This  attribute  is 
not  translated  to  network  representations  until  absolutely  necessary. 

This  function  also  updates  the  position-based  table  component  of  the  local  vehicle. 

This  can  be  called  for  Local  vehicles  only. 


3.26  ent_set_rotation 


void  ent.set.rotationCvehicle.id,  rotation) 
int32  vahicla.id; 
float64  rotation [3] [3] ; 


‘vehicle_id’ 

Specifies  the  vehicle  ID. 

‘rotation’ 

Specifies  the  new  rotation. 

•nt.sat.rotation  is  used  to  set  the  rotation  attribute  of  vehicle  appearance.  This  attribute  is 
not  translated  to  network  representations  until  absolutely  necessary. 
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This  can  be  called  for  Local  vehicles  only. 


3.27  ent-set^rientation 

void  ent.set.orientationCvehicle.id,  rotation,  heading,  pitch,  roll) 
int32  vehicle.id; 
float64  rot at ion [3] [3] ; 
float64  heading,  pitch,  roll; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘rotation’ 

Specifies  the  new  rotation. 

‘heading’ 

‘pitch’ 

‘roll’  Specifies  the  new  orientation. 

ent.set.orientation  is  used  to  set  rotation  and  orientation  attributes  of  vehicle  appearance. 
This  attribute  is  not  translated  to  network  representations  until  absolutely  necessary. 

It  is  assumed  that  the  passed  orientation  angles  and  rotation  matrix  are  equivalent.  Note  that 
although  the  rotation  could  be  computed  from  the  angles,  or  vice-versa,  it  is  assumed  that  the  caller 
has  a  good  chance  of  knowing  some  sin,  cos,  atan,  etc.  which  we  would  rather  not  recompute. 

This  can  be  called  for  Local  vehicles  only. 


3.28  ent-set jappearance 


void  ent.set.appearanceCvehicle.id,  appearance) 
int32  vehicle. id ; 
uint32  appearance; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘appearance’ 

Specifies  the  new  appearance  bits. 
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•nt.sat.app^aranc*  is  used  to  set  appearance  attribute  of  vehicle  appearance.  This  attribute 
is  not  translated  to  network  representations  until  absolutely  necessary. 

This  function  performs  x  ■  y 

This  can  be  called  for  Local  vehicles  only. 


3.29  ent_set_appearance Jbits 


void  ent.set.appearemca.bitsfvahicle.id.  appearance) 
int32  vehicle. id: 
uint32  appearance: 


‘vehicle.id’ 

Specifies  the  vehicle  ID, 

‘appearance’ 

Specifies  the  bits  to  set. 

ent.aet.appearance.bita  is  used  to  set  some  bits  in  the  appearance  attribute  of  vehicle  ap¬ 
pearance.  This  attribute  n.  not  translated  to  network  representations  until  absolutely  necessary. 

This  function  performs  x  l«  y 

This  can  be  called  for  Local  vehicles  only. 


3.30  ent_unset-appearance_bits 


void  ent.unaat.appaaxanca.bitsfvahicle.id,  appearance) 
int32  vehicle. id ; 
uint32  appearance: 


‘vehicle.id’ 

Specifies  the  vehicb’  ID 

‘appeeurance’ 

Specifies  the  bits  to  • 
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ent.unset.appaarance.bits  is  used  to  unset  some  bits  of  the  appearance  attribute  of  vehicle 
appearance.  This  attribute  is  not  translated  to  network  representations  until  absolutely  necessarv. 

This  function  performs  x  t*  "y 

This  can  be  called  for  Local  vehicles  only. 


3.31  ent_set. cap  abilities 

void  ent.set.capabilitiesfvehicle.id,  capabilities) 
int32  vehicle.id; 

VehicleCapabilities  ecapabilities ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘capabilities’ 

Specifies  the  new  capabilities. 

ent.set.capabilities  is  used  to  set  the  capabilities  attribute  of  vehicle  appearance.  This 
attribute  is  not  translated  to  network  representations  until  absolutely  necessary. 

This  can  be  called  for  Local  vehicles  only. 


3.32  ent.set^ngine jspeed 

void  ent.sst.sngine.spssdCvshicle.id,  speed) 
int32  vehicle.id; 
uintl6  speed; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘speed’  Specifies  the  new  engine  speed. 

ent.set.engine.speed  is  used  to  set  the  engine.speed  attribute  of  vehicle  appearance.  This 
attribute  is  not  translated  to  network  representations  until  absolutely  necessary. 
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This  can  be  called  for  Local  vehicles  only. 


3.33  ent_set_velocity 


void  ent_8«t_ velocity (vehicle.id,  velocity) 
int32  vehicle.id; 
float64  velocity [3] ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘velocity’ 

Specifies  the  new  velocity. 


ent.set.velocity  is  used  to  set  the  velocity  attribute  of  vehicle  appearance.  This  attribute  is 
not  translated  to  network  representations  until  absolutely  necessary. 

This  can  be  called  for  Local  vehicles  only. 


3.34  ent_set_Artic_value 

void  ent.sat.artic.valueCvehicle.id,  artic.name,  value) 
int32  vehicle.id: 
char  *artic.naDe; 

float64  value; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘artic.name’ 

Specifies  the  name  of  the  articulation  (a  libreaider  symbol) 

‘vsdue’  Specifies  the  new  value  of  the  articulation 

ent.set.artic.value  is  used  to  set  the  value  of  an  articulation  named  name.  The  value  is 
interpreted  depending  on  the  type  of  articulation  being  set.  For  instance,  in  the  case  of  a  turret 
(such  as  one  called  “primary-turret"),  the  value  is  interpreted  as  azimuth  radians,  with  0  being 
along  the  vehicle’s  X  axis  and  rotating  counterclockwise. 


This  can  be  called  for  Local  vehicles  only. 
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3.35  ent_set^rtic_rate 

void  ent_set_artic_rate(vehicle_id,  artic.name,  value) 
int32  vehicle. id; 

char  *artic_naine: 

f loat64  value ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘artic.name’ 

Specifies  the  name  of  the  articulation  (a  libreader  symbol) 

‘value’  Specifies  the  new  value  of  the  articulation  rate 

ent.set.artic.rate  is  used  to  set  the  change  value  of  an  articulation  named  name.  The  value 
is  interpreted  depending  on  the  type  of  articulation  being  set.  For  instamce,  in  the  case  of  a  turret 
(such  as  one  called  "primarj'turret"),  the  value  is  interpreted  as  azimuth  radians  per  second, 
with  0  being  along  the  vehicle’s  X  axis  and  rotating  counterclockwise. 

This  can  be  called  for  Local  vehicles  only. 


3.36  ent_get^xercise Jd 

uintS  ent.get.exercise.idCvehicle.id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

ent.get.ezercise.id  is  used  to  get  the  e.\ercise  ID  of  a  vehicle. 
This  can  be  called  for  Any  vehicle. 


3.37  ent.get_vehicle.class 

VehicleClass  ent_get.vehicle_class(vehicle_id) 
int32  vehicle.id; 


22 


LibEntity  Programmer’s  Guide 


‘vehicle. id’ 

Specifies  the  vehicle  ID. 

ent.get.vehicle.class  is  used  to  get  the  vehicle_class  attribute  of  vehicle  appearance.  When 
translations  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done 
upon  invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.38  ent.get-force Jd 

ForcelO  ent_get_forc«_id(vehicl«.id) 
int32  vehicle.id; 

‘vahicla.id’ 

Specifies  the  vehicle  ID. 

«nt_g«t. force,  id  is  used  to  get  the  force  Jd  attribute  of  vehicle  appearance.  When  translations 
from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.39  ent.get ..guises 


void  ent.get.guises (vehicle. id,  guises) 
int32  vehicle.id; 

VehicleGuises  *guises ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘guises’  Returns  the  guises 

ent.get.guises  is  used  to  get  the  guises  attribute  of  vehicle  appearance.  When  translations 
from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 
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This  can  be  called  for  Any  vehicle. 


3.40  ent.^et_guise 

ObjectType  •nt.get.guiseCvehicle.id,  vleuing.forca) 
int32  vehicla.id; 

ForcelD  vi««ing_f ore* ; 

‘vehicle_id’ 

Specifies  the  vehicle  ID. 

‘viewing_force’ 

Specifies  the  force  of  the  viewer. 

•nt.gat.guisa  is  used  to  get  the  guise  attribute  of  vehicle  appearance.  When  translations  from 
network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon  invocation 
of  the  get  function,  and  saved  for  future  calls. 

Unlike  ent.get.guises  (see  (undefined)  [ent  get'guises],  page  (undefined)),  this  function  gets 
the  appropriate  guise  relative  to  the  passed  viowingjorce. 

This  can  be  called  for  Any  vehicle. 


3.41  ent_get  jmarking 

void  •nt.gat.markingCvehicle.id,  marking} 
int32  vahicla.id; 

VahiclaMarking  ^marking; 

‘vehicle. id’ 

Specifies  the  vehicle  ID. 

‘narking’  Returns  the  marking. 

*nt_gat_narking  is  used  to  i  h*-  tiiarking  attribute  of  vehicle  appearance.  When  translations 
from  network  representation  to  lut.-riial  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  .irni  -.ivm!  fnr  future  calls. 

This  can  be  called  for  Any  \<  Im 
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3.42  ent_get^osition 


void  •nt_get.po8ition(vehicl«_id,  position) 
int32  vehicle.id; 
float64  position[3] ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘position’ 

Returns  the  position. 

ent.get.position  is  used  to  get  the  position  attribute  of  vehicle  appearance.  When  translations 
from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.43  ent_get jrotation 

void  snt.get.rotation(vshicls_id,  rotation) 
int32  vehicle.id; 
float64  rotation [3] [3] ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘rotation’ 

Returns  the  rotation. 

ent.get.rotation  is  used  to  get  the  rotation  attribute  of  vehicle  appearance.  When  transla¬ 
tions  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.44  ent.get.jorientation 
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void  ent_g«t_ori«ntation(vehicle_id,  heading,  pitch,  roll) 
int32  vehicle. id; 
float64  eheading; 
float64  epitch; 
float64  eroll; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘heading’  Returns  the  heading  (0  ==  East,  increasing  counter-clockwise). 

‘pitch’  Returns  the  pitch  (0  ==  Level,  increasing  up). 

‘roll’  Returns  the  roll  (0  =  =  Level,  increasing  counter-clockwise). 

ent.get.orientation  is  use  to  get  the  orientation  attribute  of  a  vehicle.  When  translations 
from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

If  the  vehicle  orientation  was  set  with  ent.set.orientation,  this  is  computationally  inexpen¬ 
sive.  If,  however  the  orientation  was  set  with  ent.set.rotation,  many  transcendental  operations 
are  required.  Either  way,  the  returned  data  will  be  valid. 

Pass  a  NULL  pointer  for  any  unwanted  values. 

This  can  be  called  for  Any  vehicle. 


3.45  ent_get ^direction 

void  ent.get.directionC vehicle. id,  direction) 
int32  vehicle.id; 
float64  direction [3] ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘direction’ 

Returns  the  direction. 

ent_get.direction  is  used  to  get  the  direction  attribute  of  vehicle  appearance.  When  transla¬ 
tions  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 
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Note  that  direction  is  derived  from  rotation,  but  will  be  cheaper  to  compute  than  rotation  under 
DIS. 

This  can  be  called  for  Any  vehicle. 


3.46  ent-get_appearance 

uint32  ent.get.appearancefvahicle.id) 
int32  vehicle. id: 

‘vehicle. id’ 

Specifies  the  vehicle  ID. 

ent. get.  appearance  is  used  to  get  the  appearance  attribute  of  vehicle  appearance.  When 
translations  from  network  representation  to  internal  representation  are  necessary,  these  will  be 
done  upon  invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.47  ent.get jcapabilities 

void  ent.get.capabilitiesCvehicle.id,  capabilities) 
int32  vehicle.id; 

VehicleCapabilit ies  ecapabilities ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘capabilities’ 

Returns  the  capabilities. 

ent.get.capabilities  is  used  to  get  the  capabilities  attribute  of  vehicle  appearance.  When 
translations  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done 
upon  invocation  of  the  get  function,  and  saved  for  future  calls. 


This  can  be  called  for  Any  vehicle. 
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3.48  ent_get^ngine-speed 

uint 16  ent.get. engine. speed ( vehicle. id) 
int32  vehicle. id; 


Wehicle.id’ 

Specifies  the  vehicle  ID. 

ent.get.engine.speed  is  used  to  get  the  enginejspeed  attribute  of  vehicle  appearance.  When 
translations  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done 
upon  invocation  of  the  get  function,  and  saved  for  future  calls. 


This  can  be  called  for  Any  vehicle. 


3.49  ent.get_velocity 

void  •nt.got.valocityfvehicle.id,  velocity) 
lnt32  vehicle.id; 
float64  velocity [3]; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘velocity’ 

Returns  the  velocity. 

ent.get.velocity  is  used  to  get  the  velocity  attribute  of  vehicle  appearance.  When  translations 
from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.50  ent..get^peed_square<l 

f loat64  ent .get _ speed. squared (vehicle.id) 
int32  vehicle.id; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID. 

•nt_get_8pMd_squar«d  is  used  to  got  the  speed^^squared  attribute  of  vehicle  appearance.  When 
translations  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done 
upon  invocation  of  the  get  function.  an<l  saved  for  future  calls. 

Note  that  speed^quared  is  derived  from  velocity,  but  since  the  value  will  be  cached  within 
libentity,  it  is  better  to  call  this  function  than  to  call  ent^et.velocity  and  compute  speed  squared 
manually. 

This  can  be  called  for  Any  vehicle. 


3.51  ent_get_speed 

floated  •nt.gat.spaadCvahicla.id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

ent.get_apeed  is  used  to  get  the  speed  attribute  of  vehicle  appearance.  When  translations  from 
network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon  invocation 
of  the  get  function,  and  saved  for  future  calls. 

Note  that  speed  is  derived  from  speed  squared,  but  since  the  value  will  be  cached  within  libentity, 
it  is  better  to  call  this  function  than  to  call  cnt^et.velocity  or  ent.gct.speed^quared  and  compute 
speed  manually. 

This  can  be  called  for  Any  vehicle. 


3.52  ent..g;et ^stationary 

int32  ent.get.s t at iona r 7 (vehicle.id) 
int32  vehicle.id: 
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‘vehicle.id’ 

Specifies  the  vehicle  ID. 

•nt.get.stationary  is  used  to  get  the  stationary  attribute  of  vehicle  appearance.  When  trans¬ 
lations  from  network  representation  to  internal  representation  are  necessary,  these  will  be  done  upon 
invocation  of  the  get  function,  and  saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.53  ent_get_jBrtic^uler 


void  •nt_gat_artic_euler(vehicl«.id,  artic.name,  yav,  pitch,  roll) 
int32  vehicle. id; 

char  *artic.nane; 
float64  *ya«; 
float64  epitch; 
float64  eroll; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘artic.nane’ 

Specifies  the  name  of  the  articulation  (a  libreader  symbol) 

‘yaw’  Returns  the  yaw  value  (in  radians)  of  the  articulation 

^pitch’  Returns  the  pitch  value  (in  radians)  of  the  articulation 
‘roll’  Returns  the  roll  value  (in  radians)  of  the  articulation 

ent_get_artic_euler  is  used  to  get  the  euler  angles  for  an  articulation  named  artic.name. 
Any  of  the  pointers  for  yav,  pitch,  or  roll  can  be  NULL,  in  which  case  that  component  of  the 
articulation  value  will  not  be  returned. 


This  can  be  called  for  Any  vehicle. 


3.54  ent..^et.Artic^uler j*ate 


void  ent.get.artic.euler.rateCvehicle.id,  artic.naae, 

yav.rate.  pitch.rate,  roll.rate) 

int32  vahicla.id; 
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char  *artic_naBe; 
float64  *ya«.rata; 
float64  *pitch_rata; 
float64  *roll_rata; 

‘vahicle.id’ 

Specifies  the  vehicle  ID. 

'artic.nanw' 

Specifies  the  name  of  the  articulation  (a  libreader  symbol) 

‘yaw.rate’ 

Returns  the  yaw  rate  (in  radians  per  second)  of  the  articulation 
‘pitch_rata’ 

Returns  the  pitch  rate  (in  radians  per  second)  of  the  articulation 

‘roll.rata’ 

Returns  the  roll  rate  (in  radians  per  second)  of  the  articulation 

ent.gat.airtic.aular.rata  is  used  to  get  the  euler  rates  for  an  zurticulation  named  artic.naffla. 
Any  of  the  pointers  for  yav.rata,  pitch_rate,  or  roll.rate  can  be  NULL,  in  which  case  that 
component  of  the  articulation  rate  will  not  be' returned. 

This  can  be  called  for  Any  vehicle. 


3.55  ent-get jartic_pivot 


void  ent_g«t_artic_pivot(vehicle_ld,  artic_name,  position) 
int32  vehicle,  id ; 

char  *artic_naBe ; 

float64  positionCsj ; 


‘vehicle. id’ 

Specifies  the  vehicle  ID. 

‘artic.name’ 

Specifies  the  name  of  the  articulation  (a  libreader  symbol) 

‘position’ 

Returns  the  position  of  the  pivot  point  (in  vehicle  coordinates)  of  the  articulation. 


ent.get.artic.pivot  is  used  to  get  the  pivot  point  for  an  articulation  named  artic.nane. 
For  example,  the  pivot  point  for  a  gun  is  the  base  of  the  gun,  and  the  pivot  point  for  a  turret  is 
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the  location  of  the  axis  of  rotation. 


This  can  be  called  for  Any  vehicle. 


3.56  ent_get^rtic_position 


void  ent.get.artic.positionCvehicle.id.  artic.nane.  position) 
int32  vehicle.id; 
char  •artic.nane ; 
float64  position C33 : 


‘vehicle.id* 

Specifies  the  vehicle  ID. 

^artic.nane’ 

Specifies  the  name  of  the  articulation  (a  libreader  symbol) 

^position’ 

Returns  the  position  of  the  end  point  (in  vehicle  coordinates)  of  the  articulation. 

ent.get.artic.position  is  used  to  get  the  position  for  an  airticulation  named  artic.nane. 
For  example,  the  position  for  a  gun  is  the  tip  of  the  gun.  The  position  for  a  turret  is  the  location 
of  the  axis  of  rotation  since  a  turret  doesn’t  usually  have  a  unique  length. 

This  can  be  called  for  Any  vehicle. 


3.57  ent_get jartic_rotation 


void  ent.get.artic.rotationCvehicle.id,  artic.nane,  rotation) 
int32  vehicle. id ; 

char  *artic.nane: 
float64  rotation [3] [3] ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘artic.nane’ 

Specifies  the  name  of  the  artictilation  (a  libreader  symbol) 

‘rotation’ 

Returns  the  rotation  matrix  for  the  articulation. 
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•nt_g«t.artic_rotation  is  used  to  get  the  rotation  matrix  for  am  articulation  named  artic.nana. 
This  rotation  matrix  can  be  used  to  transform  a  position  in  articulation  coordinates  into  vehicle  co¬ 
ordinates.  Note  that  to  do  the  transformation  completely,  you  will  have  to  consider  the  articulation 
position  (see  (undefined)  [enfget'artic'position],  page  (undefined)). 

This  can  be  called  for  Any  vehicle. 


3.58  ent_get_turret ^articulation 


void  ant_gat.turrat_articulation(vehicl«_id,  articulation) 
int32  vehicla.id; 

DIS.ARTICULATIOH.PARAMETER  ♦articulation; 


‘vahicla.id’ 

Specifies  the  vehicle  ID. 

‘articulation’ 

Returns  the  DIS  representation  of  the  turret’s  orientation 
•nt.get.turrat.articulation  is  used  to  get  the  DIS  representation  of  a  turret’s  orientation. 


This  can  be  called  for  Any  vehicle. 


3.59  ent_get_rotation jsp 

void  ant_gat_rotation_sp(v«hicle_id,  rotation) 
int32  vahicle.id; 
float32  rotation [3] [3] ; 

‘vehicle. id’ 

Specifies  the  vehicle  ID. 

‘rotation’ 

Returns  the  rotation  (in  single  precision). 

ent_get.rotation.sp  is  used  to  get  the  rotation  attribute  of  vehicle  appearance  (single  preci¬ 
sion  version  needed  to  build  appearance  packets).  When  translations  from  network  representation 
to  internal  representation  are  necessary,  these  will  be  done  upon  invocation  of  the  get  function,  and 
saved  for  future  calls. 
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This  can  be  called  for  Any  vehicle. 


3.60  ent_get_velocity-sp 

void  ont_get_v«locity_8p(v«hicle.id,  velocity) 
int32  vehicle.id; 
float32  velocity [3]; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘velocity’ 

Returns  the  velocity  (in  single  precision). 

ent.get.velocity.sp  is  used  to  get  the  velocity  attribute  of  vehicle  appearance  (single  precision 
version  needed  to  build  appearance  packets).  When  translations  from  network  representation  to 
internal  representation  are  necessary,  these  will  be  done  upon  invocation  of  the  get  function,  and 
saved  for  future  calls. 

This  can  be  called  for  Any  vehicle. 


3.61  ent..get4>hysdb 

PHYSDB.OATA  *ent_get.phy8db( vehicle.id) 
int32  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID. 

ent.get.physdb  looks  up  the  obj«H-t  type  of  the  vehicle  in  the  physdb  database  (see  section 
‘physdbjcey’ in  LibPhysDB  Program tiier's  .Manual).  The  returned  data  is  a  pointer  to  the  physical 
information  typical  of  an  object  wit  h  t  hat  object  type  (such  as  its  dimensions).  Because  of  the  lazy 
evaluation  and  cacheing,  calling  ilii'  function  will  yield  better  performance  that  calling  otin.query 
explicitly  (see  section  ‘otm.xiuefy' m  1  iNO  IMatch  Programmer’s  Manual). 


This  can  be  called  for  Any  le. 
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3.62  ent_get-altitude_jagl 


float64  «nt_get_altitude_agl(vahicle_id,  ctdb) 
int32  vehicle.id; 

CTDB  *ctdb; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘ctdb’  Pointer  to  the  CTDB  terrain  database  structure. 


ent.get.altitude.agl  is  used  to  get  the  altitude  AGL  (Above  Ground  Level)  of  a  vehicle. 


Note  that  altitudejagl  is  derived  from  position,  but  since  the  value  will  be  cached  within  libentity. 
it  is  better  to  call  this  function  than  to  call  ent.get_position  and  compute  altitude  AGL  manually. 


This  can  be  called  for  Any  vehicle. 


3.63  ent...get^is.guises 


void  ent.get.dis.guises (vehicle.id,  regular,  alternate) 
int32  vehicle.id; 

DIS.ENTITY.TYPE  ♦regular; 

DIS.EKnTY.TYPE  ealtemate; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘regular’  Pointer  to  the  regular  DIS  guise  for  the  vehicle. 

‘edtemate’ 

Pointer  to  the  alternate  DIS  guise  for  the  vehicle, 
ent.get.die.guises  is  used  to  get  the  normal  and  alternate  DIS  guises  of  a  vehicle. 
This  can  be  called  for  Any  vehicle. 


3.64  ent-get^is Jocation 
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void  •nt_g«t_di8_location(vehicle_id,  location) 
int32  vehicle. id; 

float64  *location: 


‘vehicle. id’ 

Specifies  the  vehicle  ID. 

‘location’ 

Pointer  to  the  DIS  location  for  the  vehicle. 

ent.get.dia.location  is  used  to  get  the  DIS  location  (in  a  Z-down  GCC  coordinate  system) 
of  a  vehicle. 

This  can  be  called  for  Any  vehicle. 


3.65  ent.^et^is_velocity 


void  ent.get.dis. velocity (vehicle.id,  velocity) 
int32  vehicle.id; 
float32  ♦ velocity; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘velocity’ 

Pointer  to  the  DIS  velocity  for  the  vehicle. 


ent.get.dis.velocity  is  used  to  get  the  DIS  velocity  (in  a  Z-down  GCC  coordinate  system) 
of  a  vehicle. 


This  can  be  called  for  Any  vehicle. 


3.66  ent_get^is_orientation 


void  ent.get.dis.orientationC vehicle.id,  orientation) 
int32  vehicle.id; 

DIS.EULER_ANGLE  '^orientation; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID. 

'orientation' 

Pointer  to  the  DIS  velocity  for  the  vehicle, 
ent.get.dis.orientation  is  used  to  get  the  DIS  orientation  of  a  vehicle. 
This  can  be  caUed  for  Any  vehicle. 


3.67  ent_get_idis_appearance 

DIS.ENTITY. APPEARANCE  ent_get_dis_appearance( vehicle. id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID. 

ent.get.dis.appearance  is  used  to  get  the  DIS  appearance  bits  of  a  vehicle. 
This  can  be  called  for  Any  vehicle. 


3.68  ent.get.xl  is  .cap  abilities 


void  ent.get.dis.capabilitiesCvehicle.id,  capabilities) 
int32  vehicle.id; 

DIS.EHnTY_CAPABILITIES  ecapabilities ; 


‘vehicle.id’ 

Specifies  the  vehicle  ID. 

‘capabilities’ 

Pointer  to  the  DIS  capabilities  for  the  vehicle. 
ent.get.di8.capabilitie8  is  used  to  get  the  DIS  capabilities  bits  of  a  vehicle. 


This  can  be  called  for  Any  vehicle. 
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4  A  ccess  K  eys 


In  addition  to  the  get  functions  just  described,  iibentity  also  provides  libaccess  keys  with  which 
many  variables  can  be  fetched  at  once.  These  keys,  and  the  type  of  argument  they  expect  are  given 
below; 

entjexerciseJd 

uintS  *arg 
ent.vehiclejclass 

VehlcleClaas  *arg 

entJbrceJd 

ForcelD  *arg 

ent^uises  VehlcleGuises  *arg 
entjoiarking 

VehicleMarking  *arg 

ent^posJtlon 

float64  arg[3] 

eatjrotstJoa 

float64  argC3]  [3] 
entjdirectioa 

float64  argC3] 
en  tjippearance 

uint32  *arg 
en  tjcapabilities 

VehicleCapabilities  *arg 
entjengine^peed 

uintlG  *arg 

entjvelocity 

float64  argC3] 
eatjpeed^quared 

float64  aarg 
ent^peed  float64  *arg 
entjstationary 

int32  4‘arg 
eat^otatioa^p 

float32  arg[3]  [3] 
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eat.velocityjp 

float32  argC3] 

ent.pbysdb 

PHYSDB.DATA  **arg 

en  tjdisjocatioa 

DIS.WORLD.COORDINATES  •arg 

eatjdis.velocity 

DIS.VECTOR  •arg 

en  tjdisjiriea  tatioa 

DIS_EULER_ANGLE  *arg 

en  ^disappearance 

DIS.EirriTY.APPEARANCE  •arg 

ent_dis_capabiZities 

DIS.ENTITY.CAPABILITIES  -arg 
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1  Overview 


Libeonorder  inplements  an  enabling  task  which  checks  an  associated  task  authorization  object. 
If  the  authorized  bit  is  set,  libeonorder's  predicate  function  returns  TRUE,  otherwise  it  returns 
FALSE.  The  GUI  code  is  responsible  for  setting  the  authorization  bit.  When  the  predicate  function 
is  invoked,  it  first  checks  to  see  if  the  task  authorization  object  exists  as  a  reference  in  the  task’s 
state  object.  If  the  authorization  object  does  not  yet  exist,  it  is  created. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libeonorder,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

2.1  eonoJnit 

void  aono.initC) 

eono.init  initializes  libeonorder.  Call  this  before  any  other  libeonorder  function. 


2.2  eonouclass Jnit 

void  eono.class.initCparent.class) 

CLASS.PTR  parent.class ; 

‘parant.class’ 

Class  of  the  parent  (declared  with  class.daclara.class) 

aono.class.init  creates  a  handle  for  attaching  eonorder  class  information  to  vehicles.  The 
parant.claiss  will  likely  be  safobj  .class. 


2.3  eono^reate 


void  aono.craataCvahicla.id,  params,  po.db) 
int  vahicla.id; 

EOHORDEIt.PAIlAMETRIC.DATA  ^parains; 
PO.DATABASE  *po.db; 


‘vahicla.id’ 

Specifies  the  vehicle  ID 
‘params’  Specifies  initial  parameter  values 
‘po.db’  Specifies  the  PO  DATABASE  used  for  the  exercise 
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•ono.create  creates  the  eonorder  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


2.4  eono.jdestroy 

void  «ono_d«stroy(vehicle.id) 
int  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

eono.destroy  frees  the  eonorder  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class. free. uaer.data. 


2.5  eonoucreate_task 

PO.DB.ENTRY  *eono.create.task(po.db} 

PQ.DATABASE  epo.db; 

‘po.db’  Specifies  the  PO  DATABASE  for  the  exercise 

eono.delete.task  creates  an  enabling  class  with  model  SH.E0a0rder.  When  the  task  is  cre¬ 
ated,  no  state  references  are  created. 


2.6  eono jdelete.task 

int32  eono.delete.taskCpo.db,  eonorder. task) 
PQ.DATABASE  epo.db; 

PO.DB.ENTRY  seonorder.task; 

‘vehicle.id’ 

Specifies  the  vehich*  ID 

‘eonorder.task’ 

Specifies  the  enabling  t.i«k  to  ho  destroyed 
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•ono.delete.task  destroys  the  specified  on-order  enabling  task,  along  with  its’  referenced 
authorization  object  (if  any). 
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1  O  vervie w 


Libetcm  implements  an  enabling  task  which  detects  when  a  unit  is  about  to  cross  a  control 
measure.  The  criteria  which  libetcm  uses  to  detect  this  are  context-dependent  and  include  the 
previous  taskframe,  i.e.  what  the  unit  is  currently  doing,  eis  well  as  the  taskframe  containing  the 
enabling  task,  i.e.  what  the  unit  would  do  if  libetcm’s  predicate  returned  a  non-zero  value.  This 
contextual  "matrix,"  as  well  as  the  simulation  state  of  the  unit,  are  used  by  the  predicate  function 
registered  by  libetcm  with  libtask.  The  contextual  information  is  known  to  the  task  manager  and 
is  passed  in  the  argument  list  to  the  predicate  function  of  the  enabling  task  when  it  is  called: 


PO.OB.ENTRY  *currant_opaqua_task_f rame : 
PO.DB.ENTRY  *next_ta8k_f rama ; 


In  addition,  the  following  information  is  passed  to  the  predicate  function  when  it  is  called  in 
case  the  current  executing  task  frame  does  not  provide  enough  context  for  the  predicate  function 
to  make  its  decision,  e.g.  the  current  frame  is  a  transparent  override: 


int32  numbar.of.axacuting. tasks; 

PO.DB.ENTRY  *axecuting.tasks [] ; 


This  library  is  also  responsible  for  setting  the  shared  parameters  of  the  appropriate  task  in  the 
task  frame  pointed  to  by  PO.DB.ENTRY  anaxt_task_f rame. 


For  example,  suppose  a  unit  is  following  a  route  and  is  about  to  cross  a  phase  line,  where 
the  unit  has  been  ordered  to  launch  an  assault.  The  control  measure  enabling  task  is  responsible 
for  calculating  how  far  away  from  the  phase  line  the  unit  must  begin  to  prepare  for  the  assault. 
Libetcm’s  predicate  function  returns  a  non-zero  value  when  the  unit  reaches  this  location.  This 
library  is  also  responsible  for  setting  the  shared  parameters  of  the  prepare-to-assault  task  in  its 
own  frame  so  that  the  prepare-to-assault  task  wiU  be  able  to  prepare  for  the  assault.  This  may 
invovle  slowing  the  unit  down,  keeping  to  the  projected  path  along  its  current  route,  and  halting 
at  the  desired  location  in  preparation  for  the  assault. 


The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘f8in2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 


Libetcm  depends  on  libuflwrte,  iibpo,  libclass,  libctdb,  libaccess,  libreader,  and  libparmgr. 
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1.1  Task  Parameters 

The  format  of  the  parametric  data  is  as  follows; 

(SH_ETCN  (vaypt.error  <distanc«  ffleters>) 

) 

The  waypt.error  parameter  specifies  the  distance  from  a  vertex  of  a  control  measure  at  which 
a  vehicle  will  perceive  that  it  has  crossed  the  control  measure. 

1.2  Task  Parameters 

In  enabling  tasks  for  control  measures,  the  parameter  block  of  the  task  data  structure  is  empty. 
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2  Fun  ctio  n  s 

The  following  sections  describe  each  function  provided  by  libetcm,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  etcmJnit 

void  etcin.init() 

•tcin_init  initializes  libetcm.  Call  this  before  any  other  libetcm  function. 


2.2  etcm ^lass Jnit 

void  etciii_class.init(parant_cla88) 

CLASS.PTR  parent.cla88 : 

‘par«nt_cla88’ 

Class  of  the  parent  (declared  with  cla88.declar8_cla88) 

etcin_cla88_init  creates  a  handle  for  attaching  etcm  class  information  to  vehicles.  The  parent.class 
will  likely  be  aafobj.claaa. 


2.3  etcm  .create 

void  atc]ii_craata(vehicle.id,  paraoa,  po.db,  ctdb) 
int  vahicla.id; 

ETCILPAIUMETRIC.DATA  *para]n8; 

PO.DATABASE  *po.db; 

CTDB  ♦ctdb; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘parama’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

•tcoucreat*  creates  the  etcm  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block  of 
libclass  user  data. 


2.4  etcm_destroy 

void  etcm_destro7(vehicle_id) 
int  vehicla.id; 

’vehicle. id’ 

Specifies  the  vehicle  ID 

etcoLdestroy  frees  the  etcm  class  information  for  a  vehicle.  This  should  be  called  before  freeing 
the  class  user  data  with  class  .free.user.data. 


2.5  etcmunit_task..state 

void  etcm.iziit.task_state(task,  state) 

TaskClass  etask; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  a  new  SN_ETCH  task  that  is  about  to  be  created,  etcin.init_task_state  initializes  the 
model  size,  and  state  variables. 
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1  Overview 


Libexecmat  creates  the  execution  matrix  editor  for  units  and  subordinate  units.  The  execution 
matrix  is  used  to  create  and  assign  missions.  A  mission  is  made  up  of  a  series  of  task  frames 
separated  by  control  measures  (a  control  measure  can  be  NULL).  Reaching  a  control  measure 
advances  the  mission  to  the  next  task  frame.  The  control  measure  is  referred  to  as  an  ETCM 
(Enabling  Task  Control  Measure)  because  reaching  this  control  measure  enables  the  mission  to 
advance  to  the  next  task  frame.  A  task  frame  can  be  made  "On  Order".  A  mission  will  stay  in  its 
current  task  frame  if  the  next  task  frame  is  "On  Order".  Authorizing  an  "On  Order"  advances  the 
mission  to  the  authorized  task  frame. 


Each  displayed  task  frame  is  really  made  up  of  two  task  frames  -  the  Preparatory  task  frame 
and  the  Actual  task  frame.  Only  the  Actual  task  frame  is  displayed  in  the  execution  matrix.  The 
task  frame  editor  MUST  return  the  two  task  frames  linked  together  by  the  previousMissionFraa* 
field.  Each  task  frame  has  a  primary  task  which  is  used  to  determine  whether  the  task  frame  is 
finished.  (If  the  primary  task  is  done,  the  task  frame  is  done.) 

In  addition  to  the  ETCM  enabling  task,  there  is  another  enabling  task  called  the  In-Phase 
enabling  task.  The  In-Phase  enabling  task  determines  whether  the  unit’s  peer  units  are  in  the 
same  phase  as  it  is.  This  is  done  by  seeing  if  the  peer  units  have  completed  their  preparatory  task 
frames  for  the  same  phase. 


In  each  of  the  prep  and  actual  task  frames,  there  is  a  postfix  logic  stack  which  determines  the 
conditions  that  must  be  met  before  this  taskframe  is  executed.  The  lo^c  stack  algorithm  for  the 
preparatory  task  frame  is: 


Primary  task  of  previous  frame  is  done  OR 
ETCH  of  phase  is  crossed  OR 

On  Order  of  task  frame  has  been  given  (if  applicable) 


If  any  of  these  conditions  is  met,  the  preparatory  task  frame  is  executed. 


The  logic  stack  algorithm  for  the  actual  task  frame  is: 


Primary  task  of  prepatory  task  is  done  AND 
Other  peer  units  are  in-phase  AND 

On  Order  of  actual  task  frame  has  been  given  (if  applicable) 
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If  all  of  these  conditions  are  met.  the  actual  task  frame  is  executed.  Note  that  there  is  no 
guarantee  that  the  ETCM  of  the  phase  has  been  reached.  This  is  done  because  there  might  be 
some  user  error  where  the  ETCM  could  never  be  reached  and  the  mission  still  needs  to  advance. 

When  the  user  clicks  the  "Done"  button  on  the  execution  matrix  editor,  the  task  frames  are 
linked  intoa  mission  for  each  unit.  The  mission  is  linked  backwards  using  the  previousMisaionFraa* 
held  in  the  task  frame.  If  the  unit  has  not  already  been  assigned  a  mission,  this  mission  is  assigned 
to  the  unit.  Although  the  mission  rtxb*  is  general  enough  to  support  a  tree  structure,  the  current 
missions  are  flat. 

The  execution  matrix  editor  is  not  controlled  by  libeditor.  so  it  has  to  keep  track  of  its  own 
state  when  it  becomes  active,  suspembil.  etc. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libexecmat,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  execmatJnit 

void  exeoiiat.initO 

•xecmat.init  initializes  libexecmat.  Call  this  function  before  calling  any  other  libexecmat 
functions. 


2.2  execmat Jnit_gui 


EXECMAT.GUI.PTR  •xecaat.init.guKdata.path,  reader.f lags , 

gui,  tactnap,  tcc,  map.sraso.gc, 
sensitive,  refresh. event,  db,  exit.fcn,exit.arg} 
char  *data.path; 

int32  reader.f lags ; 

SGUI.PTR  gui; 

TACnfAP.PTR  tactmap; 

COORD.TCC.PTR  tcc; 

GC  aap.erase.gc; 

SISTVE.VIHDaW.PTR  sensitive; 

CALLBACK.EVEHT.PTR  refresh.event; 

PO.DATABASE  *db; 

ASSIGH.EXIT.FUMCTIOH  exit. fen; 

ADDRESS  exit.arg; 


‘data.path’ 

Specifies  the  directory  where  data  files  are  expected 
‘reader.flags’ 

Specifies  fla^  to  be  passed  to  reader.read  when  reading  data  files 
‘gui*  Specifies  the  SAF  GUI 
‘tactmap’  Specifies  the  tactical  map 
‘tcc’  Specifies  the  map  coordinate  system 
‘aap.erase.gc’ 

Specifies  the  GC  which  can  erase  things  from  the  tactical  map 
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‘db’  Specifies  the  persistent  object  database 

‘•xit.fcn,  exit.arg’ 

Specifies  a  function  to  call  when  the  assignment  is  completed 

•xecmat.init.gui  creates  the  execution  matrix  editor.  The  execution  matrix  editor  consists 
of  up  to  6  phases  of  tasks  for  UNIT0RG3/iAX_BREADTH  units. 


2.3  execmat.3et_unit 


void  ex«ciiiat_8«t_unit(aBigui.  unit.id.  tasking. type) 
EXECNAT.GUI.PTR  emgui; 

Object ID  *\mit_id; 

EXECMAT.TASKING.TYPE  tasking. type; 


‘emgui’  Specifies  EXECMAT_GUIJ*TR  data  structure 
‘unit.id’  Specifies  the  unit  id. 

‘tasking. type’ 

Specifies  SUBORDINATE.TASKING  or  UNIT.TASKING 


execmat.set.unit  fills  in  the  emgui  data  structure  units  with  either  the  unitJd  passed  in 
or  subordinate  units  of  the  unitJd  passed  in  depending  on  the  tasking.type.  If  the  units  (or 
subordinate  units)  are  currently  executing  a  mission,  their  po  task  frames  are  retrieved  amd  filled 
into  the  emgui  data  structure  as  well  as  the  pushbutton  widgets  of  the  matrix  user  interface.  The 
names  of  the  units  are  retrieved  from  the  unit  po  and  filled  in  the  label  widgets  of  the  matrix  user 
interface. 


2.4  execinat.create 


void  exscmat.statsCgui,  mode,  state) 
EXECIUT.GUI.PTR  gui; 
SGUI.MODE.PTR  mode; 
SGUI.MODE.STATE  state; 


‘.mi  ’ 

gUl 

‘mode’ 

‘state’ 


Specifies  the  SAF  GUI 
Specifies  the  mode  to  use 
Specifies  the  new  state 


Chapter  2:  Functions 


5 


ezecmat.state  sets  the  state  of  the  execution  matrix  editor.  This  is  equivalent  in  functionality 
to  edt^tate(),  but  is  needed  because  the  execution  matrix  editor  is  not  controlled  by  libeditor. 
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1  O  vervie w 


libfcs  profides  a  fire-control  system  abstraction  for  SAF  vehicles  which  have  a  large  number  of 
libguns  components  (see  section  ‘Overview’  in  LibGUNS  Programmer’s  Manual),  such  as  aircraft, 
libfcs  provides  an  interface  where  weapon  launcher  commands  can  be  specified  in  terms  of  the 
munition  which  will  be  fired;  libfcs  uses  selection  algorithms  to  determine  which  launcher  is  most 
suitable  to  direct  the  libguns  commands  for  a  given  munition.  In  the  future,  libfcs  can  be  expanded 
to  support  selection  algorithms  which  can  perform  such  tasks  as  launching  missiles  in  the  proper 
order  from  an  aircraft  with  multiple  missile  launcher  stations  in  order  to  keep  the  aircraft  as 
balanced  as  possible,  or  to  avoid  a  launched  missile  from  colliding  with  an  un-launched  missile. 

The  parameters  of  the  fire  control  system  are  specified  in  the  configuration  file  for  the  vehicle 
containing  a  libfcs  fire  control  system  as  follows: 

(SM.Fir«Control  (components  <nafflel>  <name2>  . . . ) 

) 

The  name  of  each  component  being  controlled  by  the  fire  control  system  is  specified.  Each  name 
must  be  a  gun  component  of  the  vehicle. 


LibFCS  Programmer’s  Guide 


Chapter  2:  Usage 


3 


2  Usage 


The  software  library  ‘libfcs.a’  should  be  built  and  installed  in  the  directory 
Vcommon/lib/'.  You  will  also  need  the  header  file  ‘libfcs.h’  which  should  be  installed  in  the 
directory  ‘/connnon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make’  in 
the  libfcs  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libfcs. 


2.1  Building  Libfcs 

The  libfcs  source  files  are  found  in  the  directory  ‘/common/llbsrc/libfcs’.  ‘RCS’  format  ver¬ 
sions  of  the  files  can  be  found  in  ‘/nfs/coinmon_src/libsrc/libfcs’. 

If  the  directory  ‘comuon/libsrc/libfcs’  does  not  exist  on  your  machine,  you  should  use  the 
‘ganbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

i  cd  common/llbsrc/libfcs 
i  CO  RCS/*,v 
•  make  install 

This  should  compile  the  library  ‘libfcs.a’  and  install  it  and  the  header  file  'libfcs. h’  in  the 
standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the  source 
code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libfcs  should  compile  without 
errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libfcs 

Libfcs  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id  [source 
.o  files]  -L/common/lib  -Ifcs’.  If  your  compiler  does  not  support  ‘-L’  syntax,  you  can  use  the 
archive  explicitly:  ‘Id  [source  .o  files]  /common/lib/libfcs.a’. 
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Libfcs  depends  on  libaccess  libcomponents  libreader  libguns  libparmgr  libvtab  and  libclass. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libfcs,  including  the  format  and  mean¬ 
ing  of  its  arguments,  and  the  moaning  of  its  return  values  (if  any). 


3.1  fcsjnit 

void  fcs.initC) 

fc8_init  initializes  libfcs.  Call  this  before  any  other  libfcs  functions. 


3.2  fcs_class Jnit 

void  fcs.claas.initCparent. class) 

CLASS.PTR  parent.class; 

'parent.class’ 

Specifies  the  parent  class  of  entity  (probably  safobjj:lass). 

f  cs_class_init  creates  a  handle  for  attaching  FCS  class  information  to  vehicles.  The  parent.class 
is  one  created  with  class.declare.class. 


3.3  fcs.create 

void  fcs.create (vehicle. id,  paras) 
int32  vehlcle.id; 

FCS.PAIIAMETRIC.DATA  «paras; 

‘vehicle.id’ 

Specifies  the  vehicle Jd  nf  the  vehicle  to  be  created. 

‘paras’  Specifies  parametric  f<»r  the  fire  control  system. 

fcs.create  creates  the  FCS  <  l.i-*  !tif.»rm.-ition  for  a  vehicle  and  atttaches  it  to  the  vehicle’s 
libclass  user  data. 
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3.4  fcs_:destroy 


void  fC8_destroy(v«hicl«_id) 

int32  vehicle.id; 


‘vehicle. id’ 

Specifies  the  vehicleJd  of  the  vehicle  to  be  created, 
f  cs.destroy  frees  the  FCS  class  information  for  a  vehicK 


3.5  fcsJoad 

void  fcs.loadCvehicle.id,  munition,  store,  quantity) 
int32  vehicle.id; 
uint32  munition; 
int32  store; 
int32  quantity; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘munition’ 

Specifies  the  type  of  munition  to  load 
‘store’  Specifies  from  what  store  to  load  the  munition  from 
‘quantity’ 

Specifies  the  quantity  of  munitions  to  load  into  the  gun 


f  cs.load  starts  the  loading  procedure  for  a  quantity  number  of  munitions  from  the  supplied 
store  for  an  apropriate  gun  component,  fcs.load  will  dynamically  determine  the  appropriate 
component  to  direct  the  GUHS.SET.LOAD.NUNITION  command 

(see  section  ‘GUNS3ETJ<OAD3IUNmON’  in  LibGUNS  Programmer’s  Manual)  from  the  list  of 
possible  components  specified  as  parametric  data  to  libfcs. 


3.6  fcs.quantities 


void  fcs.quantities (vehicle.id,  munition,  current. limit ,  absolute.limit) 
int32  vehicle.id; 
uint32  munition; 
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lnt32  *curr«nt_liBit: 
int32  *abBolute_lifflit; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘munition’ 

Specifies  the  type  of  munition  to  load 
‘current.limit’ 

Specifies  the  current  limit  on  this  munition  type 
‘abeolute.limit’ 

Specifies  the  absolute  limit  on  this  munition  type 


fcs.quantities  returns  (by  reference)  the  current  and  absolute  maxima  of  the  number  of 
rounds  that  the  PCS  can  fire  of  the  specified  munition  type  on  the  given  vehicle.  These  quantities 
are  related  to  but  not  necessarily  equal  to  supplies  available  and  should  be  interpreted  as  how  many 
rounds  the  FCS  can  fire  given  unlimited  supplies.  These  may  be  based  on  limitations  of  the  actual 
weapons  or  implementations  of  the  code  modeling  the  weapons. 


3.7  fcs_ready 


void  fcs.readyCvehicle.id,  munition,  ready,  missile.id) 
int32  vehicle.id; 
uint32  munition; 
int32  *ready; 
int32  *mis8ile_id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘munition’ 

Specifies  the  munition  to  check 

‘ready’  Returns  whether  a  gun  containing  the  specified  munition  is  ready  for  firing 
‘id’  Returns  vehicle  ID  of  a  ready  missile 


fc8.ready  returns  (by  reference)  whether  an  appropriate  gun  component  is  ready  to  fire  the 
requested  munitioxL  For  missile  launchers,  the  vehicle  ID  of  the  ready  missile  is  returned  (by 
reference)  as  well.  A  gun  is  generally  not  ready  if  it  is  not  loaded  or  is  in  the  proc'^^o  of  loading  or 
unlosuling  munitions. 
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fcs.ready  will  dynamically  determine  the  appropriate  component  to  direct  the 
GUNS.GET.READY.TO.FIRE  command  (see  section  ‘GUNS_GETJlEADY_TO  JIRE’  in  LibGUNS 
Programmer’s  Manual)  from  the  list  of  possible  components  specified  as  parametric  data  to  libf  cs. 


3.8  fcs_fire 


void  fcs.fireCvehicle.id.  munition,  quantity) 
int32  vehicle. id: 
uint32  mimition; 
int32  quantity; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘munition’ 

Specifies  the  munition 

‘quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 


f  cs.f  ire  attempts  to  launch  a  weapon  of  the  specified  munition  from  one  of  the  possible  guns 
in  the  fire  control  system.  The  weapon  is  fired  in  whatever  direction  it  is  currently  pointing. 

f  ce.f  ire  will  dynamically  determine  the  appropriate  component  to  direct  the  GUMS_SET.FIIIE 
command  (see  section  ‘GUNS^ETJ'IRE’  in  LibGUNS  Progrztmmer’s  Manual)  from  the  list  of 
possible  components  specified  as  parametric  data  to  It >><’'  8. 


3.9  fcs-fire-at_target 


void  fcs.fire^at.target (vehicle.id,  target.id,  munition,  quantity) 
int32  vehicle. id ; 
int32  target.id; 
uint32  munition; 
int32  quantity; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘target.id’ 


Specifies  the  target  to  fire  at 
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‘ounition’ 

Specifies  the  munition 

‘quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 

f  cs_f  ire.at.target  attempts  to  launch  a  weapon  of  the  specified  munition  from  one  of  the 
possible  guns  in  the  fire  control  system.  The  weapon  is  fired  with  the  intent  to  hit  the  target,  if 
possible.  If  the  weapon  is  a  guided  munition  (such  as  a  missile),  there  may  be  other  actions  required 
during  the  flight  of  the  munition  to  ensure  that  it  will  hit  the  target. 

f  ca_f  ire_at_target  will  dynamically  determine  the  appropriate  component  to  direct  the  GUirS_SET_FIRE_ 
command  (see  section  ‘GUNS^ET  JIRE-AT-TARGET’  in  LibGUNS  Programmer’s  Manual)  from 
the  list  of  possible  components  specified  as  parametric  data  to  libfca.  • 


3.10  fcs_fire_at_location 


void  fcs.fira.at.locationCvohicle.id,  location,  munition,  quantity) 
int32  vehicle. id; 

lloat64  locationCsj ; 
uint32  munition: 
int32  quantity; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘location’ 

Specifies  the  location  to  fire  at 

‘munition’ 

Specifies  the  munition 

‘quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 


f  cs.f  ire.at.location  attempts  to  launch  a  weapon  of  the  specified  munition  from  one  of  the 
possible  guns  in  the  fire  control  system.  The  weapon  is  fired  with  the  intent  to  hit  the  location, 
if  passible.  If  the  weapon  is  a  guided  munition  (such  as  a  missile),  there  may  be  other  actions 
required  during  the  flight  of  the  munition  to  ensure  that  it  will  hit  the  location. 


fcs.fire.at.location  will  dynamically  determine  the  appropriate  component  to  direct  the 
GUNS.SET.FIFIE.AT.LOCATION  command  (see  section  ‘GUNSJSETJIREJVTXOCATION’  in  Lib- 
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GUNS  Programmer’s  Manual)  from  the  list  of  possible  components  specified  as  parametric  data  to 
libfcs. 
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1 


1  O  vervie w 


LibFonnationDB  provides  a  database  of  named  standard  military  formations  which  can  be 
used  for  initial  placement  of  units  as  well  as  for  station  keeping  of  units  during  movement.  Lib- 
FormationDB  uses  a  database  encoded  in  libreader  format  (see  section  ‘Overview'  in  LibReader 
Programmer’s  Manual)  d  to  represent  the  placement  of  units  in  a  formation.  Note  that  in  this 
context,  the  term  ‘units’  can  refer  to  individual  vehicles  or  to  unit  aggregates  (such  as  sections, 
platoons,  companies,  etc.). 

LibFonnationDB  provides  two  primary  interface  routines  for  accessing  formation  information, 
fomdb.szpand  can  be  used  to  apply  a  formation  and  spacing  to  units  for  a  given  location  and 
direction.  Position  information  (where  a  unit  should  be  to  be  in  station)  is  returned,  as  well  as 
desired  scan-sectors  for  each  unit.  The  routine  can  take  current  positions  of  the  units  into  account 
in  order  to  assign  formations  which  minimize  vehicle  movement  (such  as  reversing  a  formation  or 
using  an  alternate  assignment  of  units  to  formation  stations),  f  ormdb.craata.routas  can  be  used 
to  apply  a  specified  formation  and  spacing  to  units  which  should  be  following  a  supplied  route. 
Routes  are  generated  for  each  unit  which  are  similar  to  the  input  route  and  have  the  property  that 
if  each  unit  follows  each  route,  the  units  will  appear  to  be  keeping  station,  at  least  at  the  route 
vertices.  Note  that  this  routine  is  not  suitable  for  roadmarch,  since  roadpoints  for  followers  would 
not  be  preserved. 


1.1  Algorithms 

To  be  placed  in  a  formation,  units  are  laid  out  one  at  a  time  in  lines  called  rays.  A  given 
formation  may  contain  one  or  more  rays  in  which  to  place  units.  Any  ray  (except  the  first  one 
specified)  will  refer  to  a  previously  specified  ray  to  indicate  a  reference  starting  position  for  that 
ray.  The  first  ray  in  a  formation  refers  to  no  other  ray. 

Each  ray  in  a  formation  is  given  a  unit  one  at  a  time  in  ray-breadth  order.  If  a  ray  exceeds 
some  specified  maximum  number  of  units,  that  ray  is  skipped  from  receiving  more  units.  The 
formation  laydown  algorithm  uses  data  in  the  formation  database  file  to  decide  the  order  by  which 
units  are  assigned  the  formation,  thus  allowing  the  explicit  positioning  of  specific  units  such  as  a 
unit-leader.  Additional  information  about  the  placement  algorithm  is  contained  in  the  description 
of  the  LibFonnationDB  file  format  (see  Section  1.2  [File  Format],  page  2). 

The  algorithm  used  to  minimize  vehicle  movement  in  the  assignment  of  vehicles  to  a  formation 
template  for  foxmdb.azpand  is  to  assign  vehicles  in  all  formation  orderings  and  to  choose  the  one 
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which  minimizes  crossings.  Among  those  assignments  with  the  same  number  of  crossings,  the  one 
containing  the  minimum  sum  of  of  distances  to  be  travelled  by  every  unit  is  chosen. 

The  algorithm  used  to  generate  foUower  routes  in  f  ormdb.creata.routes  is  to  use  f  ormdb.ezpemd 
at  the  begining  of  the  route  to  identify  the  starting  position  of  each  unit,  forodb.expand  is  used 
at  every  waypoint  which  is  at  least  the  specified  sampling  distance  apart.  At  those  waypoints, 
the  direction  chosen  is  the  mean  of  the  incoming  and  outgoing  directions.  The  formation  ordering 
remains  constant  over  an  entire  route.  Route  segments  are  inferred  as  straight  line  connections 
between  formation  expanded  waypoints. 


1.2  File  Format 


Formation  information  is  stored  in  the  formation  database  ‘fozmdb.rdr’  as  follows: 


(<foniiation_naffle> 

(<ray'8pecifierl> 

<ra7-8pecifi«r2> 

...) 

(<plac«m«nt-nunb«rl>  <plac«nent-nuiBbar2>  <placaiiiaa.t-nuBbar3>  ...) 
<oth«r  placement  Ii8t8> 

•  •  • 

) 


<foziiiation_name>  specifies  the  name  of  the  formation. 

<ra7-8pecif  ier>  specifies  the  incremental  placement  of  vehicles  along  a  ray  as  follows: 

(<reference>  <coiDpa88_off8et>  <Z_off8et>  <8pacing_factor>  <iiiax>) 

<reference>  is  the  index  of  the  ray  that  this  ray  keys  off.  The  indices  of  the  rays  are  zero-based. 
The  first  ray  on  which  a  vehicle  will  be  placed  will  have  a  reference  of  -1. 


<coiiipa88.off 8at>  indicates  the  direction  to  place  subsequent  units  from  previous  units  already 
placed  in  a  ray.  For  the  first  unit  in  a  ray,  the  <cofflpas8.off8et>  specifies  the  of&et  from  the  first 
unit  in  the  referenced  ray.  The  <compa8s_of f 8et>  for  the  first  vehicle  in  the  first  ray  is  not  used. 
The  values  of  <compa88_offset>  are  specified  by  the  following  macro  names,  which  are  defined  in 
‘fonndb.rdr’: 
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•  FORNOB.FROMT 

•  FORMDB.BACK 

•  FORMDB.RIGHT 

•  FORMDB.LEFT 

•  FORMDB.FRONT.RIGHT 

•  FORMDB.FRONT.LEFT 

•  FORHDB_BACK_RIGHT 

•  FORMDB_BACK_LEFT 


The  interpretation  of  the  <compas8_of  f  sat>  directions  are  as  in  the  following  table: 


FORMDB.FRONT.LEFT 


FORMDB.FROMT 


FORMDB.FROMT.RIGHT 


FORMDB.LEFT 


I 

l-l-l 
I  i  I 
I  I 
I - 1 


FORMDB.RIGHT 


(previously  placed 


unit) 


FORMDB.BACK.LEFT 


FORMDB.BACK 


FORMDB.BACK.RIGHT 


<Z.offset>  specifies  whether  or  not  the  placement  along  the  ray  includes  a  Z  component,  for 
3-dimensional  formations.  This  is  only  useful  for  air-formations.  The  values  for  <ZjoiTset>  can  be: 

•  FORMDB.LEVEL 

•  FORMDB.UP 

•  FORMDB.DOHN 


<spacing.factor>  specifies  a  positive  real  multiplicative  factor  to  use  when  applying  a  for¬ 
mation  spacing  to  vehicles  along  a  ray.  Vehicles  placed  on  a  diagonal  ray  will  have  an  additional 
implied  multiplicative  factor  equal  to  the  sqrt(2).  This  implies  that  a  formation  with  a  uniform 
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spacing  factor  for  all  rays  will  result  in  all  units  being  placed  on  a  virtual  grid.  For  uniform  spacing, 
the  <spacing_factor>  will  typically  be  equal  to  1.0. 

<max>  specifies  the  integer  maximum  number  of  vehicles  to  be  placed  on  a  ray.  A  value  of  *1 
means  an  infinite  number  of  vehicles  may  be  placed  on  this  ray. 

<placement-numberN>  specifies  the  assignment  order  in  which  units  are  placed  into  a  formation. 
A  unit’s  “job”  (also  referred  to  in  NUkIS.AF  as  its  promotion  index)  is  used  to  index  this  list  to 
decide  when  that  unit  should  be  placet!  with  respect  to  other  units  in  the  formation.  For  example, 
the  ordering  (2  3  14)  specifies  that  the  unit  with  a  job  of  1  should  be  placed  second,  the  unit  with 
the  job  of  2  should  be  placed  third,  the  unit  with  the  job  of  3  should  be  placed  first,  and  so  on. 
This  allows  precise  ordering  of  vehicles  in  the  formation  to  produce  tactically  correct  assignments. 
By  convention,  job  1  refers  to  a  unit  leader,  such  as  a  platoon  leader,  2  refers  to  the  leader’s 
“wingman”,  3  refers  to  the  unit's  second-in-command,  such  ais  a  platoon  sergeant,  and  4  refers 
to  the  “wingman”  of  the  second-in-conuiiand.  L’nits  with  job  numbers  greater  than  the  length  of 
the  list  will  be  placed  after  all  other  units  in  job  number  order.  Negative  indices  can  be  used  to 
represent  the  placement  of  vehicles  in  la-st-to-first  order.  For  example,  the  ordering  (-1  -2  -3  -4) 
indicates  that  the  unit  with  a  job  of  1  will  be  placed  last. 

Note  that  in  ModSAF,  “jobs”,  as  reported  in  the  taskOrglndex  and  functionalOrglndex  fields 
of  a  UnitClass  Persistent  Object,  are  inde.xed  starting  at  zero,  as  opposed  to  the  “jobs”  referred 
to  in  the  libFormationDB  data  file,  which  are  indexed  starting  at  one  (in  order  to  match  typical 
Platoon  training  manuals).  Hence,  the  assignment  for  the  unit  1  specified  in  ‘fonndb.rdr’  may  refer 
to  a  ModSAF  entity  containing  a  functionalOrglndex  of  value  0  in  its  corresponding  UnitClass 
Persistent  Object. 

See  section  ‘Unit  Class’  in  LibPO  Programmer’s  Manual. 

Multiple  placement  lists  may  be  specified  in  order  to  allow  formation  orderings  that  minimize 
crossing  of  vehicles  or  distance  travelled. 

As  an  example  of  complete  formation  specification,  the  following  could  be  used  to  specify  an 
echelon-right  formation. 

;;  Echelon  formations  are  like  column  with  a  slemt 
;;  2  2  1  1 
; ;  1  1  2  2 
; :  4  3  3  4 

; :  3  4  4  3 
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(echelon-right 

((-1  FORMDB.RIGHT.BACK  FORMDB.LEVEL  1.0  -1)) 
( ; :  Wingman  in  front 
(2  14  3) 

(2  13  4) 

; ;  Leader  in  front 
(1234) 

(1243) 

; ;  Reverse  formations 
(3  4  12) 

(4312) 

(4321) 

(3  4  2  1) 

) 


1.3  Data  Structures 


Formation  queries  utilize  the  following  data  structure  to  encode  unit  information  for  both  input 
and  output: 


t3rpedef  struct  formdb.data 

/*  Inputs  */ 
int32  job; 

float64  current_position[3] ; 
/♦  Outputs  •/ 

flo8t64  de8ired_positionC3] ; 
float64  scan_ccv; 
float64  scan.cv; 

}  FORMDB.DATA; 


The  input  fields  of  FORMDB.DATA  are  job  and  current. position,  and  they  are  used  as  input  to 
the  formationdb  query  routines.  The  remaining  fields  are  output  fields  set  by  the  query  function, 
as  follows: 


desired.po8ition  is  the  location  that  this  unit  should  should  be  at  in  order  to  be  in  formation. 


scan.ccv  and  8can.cv  define  algorithmically  generated  scan  sectors  for  the  unit,  represented 
as  counter-clockwise  and  clockwise  radians  in  vehicle  coordinates.  Zero  is  out  the  front  of  the 
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vehicle  and  increases  positively  counter-clockwise.  The  scan  limits  are  interpreted  the  same  way 
as  the  slew  limits  are  interpreted  in  libPhysDB  (see  section  ‘physdbjiearest^ngle’  in  LibPhysDB 
Programmer’s  Manual).  The  scan  sectors  generated  for  vehicles  in  a  formation  are  typical  for  that 
vehicles  in  that  formation. 

Routes  for  station  keeping  are  represented  via  the  ROUTE.POINTS  data  structure  in  ‘stdroute.h’ 

Output  routes  generated  by  the  fomdb.creata.routes  routine  wiU  have  point.id  which  ref¬ 
erence  the  indices  of  the  input  route.  Also,  because  of  input  route  sampling,  some  input  route  point 
indices  may  never  be  referenced  by  a  generated  output  route. 


1.4  Examples 

The  test  programs  ^ftest.c’  and  ‘rtest.c’  demonstrate  the  use  of  LibFormationDB  to  generate 
the  initial  placement  of  units  and  the  generation  of  station-keeping  routes,  respectively. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libFormationDB,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  formdbjnit 


int32  forndb.initCdirectory,  flags,  ctdb) 
char  *diractory; 
uint32  flags: 

CTDB  *ctdb; 


‘directory’ 

Specifies  the  directory  where  the  formdb  file  is  expected 
‘flags’  Specifies  reader  options  (see  section  ‘reader_read’  in  LibReader  Programmer’s  Manual) 

‘ctdb’  Specifies  a  CTDB  terrain  database  to  use  for  checking  formations  against  water  obsta¬ 
cles. 


fonadb.init  initializes  libformdb,  causing  it  to  read  its  data  file  ‘fomdb.rdr’  from  the  specified 
directory.  The  flags  are  as  in  raader.read.  The  return  value  is  zero  if  the  read  succeeds,  or 
one  of  the  libreader  return  values:  READER_REAO.E!UU}R  READER.FILE_HOT_FOUHD. 


Note  that  the  libreader  function  reader.init  must  be  called  before  this  function. 


2.2  formdb.jexpand 


int32  fonndb.ezpand(foniiation_name,  spacing,  direction,  location, 

optimize,  n_units,  unit.data,  assignment.key) 
char  *f ormation_naffle ; 

float64  spacing; 

float64  direction; 

float64  location [3] ; 

int32  optimize; 

int32  n_units ; 

FQRMDB.DATA  unit.data [] ; 
int32  eassignment.key; 
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‘formation  name’ 

Specifies  the  name  of  the  formation.  This  should  be  a  libreader  symbol. 

‘spacing’  Specifies  a  desired  spacing  between  units,  in  meters 
‘direction’ 

Specifies  the  desired  direction  of  the  units  in  the  formation,  in  radians.  0  is  interpreted 
as  north,  and  directions  increase  positively  counter-clockwise. 

‘location’ 

Specifies  the  desired  location  of  the  center  of  mass  of  the  formation.  If  it  is  equal  to 
[0.0,  0.0,  0.0],  then  the  center  of  mass  will  remain  unchanged. 

‘optimize’ 

Specifies  whether  to  allow  reordering  of  the  desired  formation  to  minimize  unit  crossing 
and  unit  movement. 

‘n_unit8’  Specifies  the  number  of  units  in  the  imit.data  array. 

‘unit.data’ 

Specifies  and  returns  data  for  the  units.  Desired  vehicle  placement  and  scan  sector 
information  will  be  returned  in  this  data. 

‘asaignment.kay’ 

If  optimiza  is  TRUE,  an  index  for  the  optimal  assignment  chosen  for  the  formation  will 
returned  here.  If  optimize  is  FALSE,  the  assignment  specified  by  assignment.key  will 
be  used,  assignment.key  can  be  NULL,  in  which  case  the  first  assignment  specified  in 
the  ‘f ormdb .  rdr’  database  will  be  used  if  optimize  is  FALSE. 

formdb.ezpand  calculates  desired  positions,  station-keeping  information  and  scan  sector  infor¬ 
mation  for  the  units  represented  in  the  passed  in  unit.data  to  be  in  the  specified  formation, 
spacing  and  direction.  Note  that  the  input  fields  of  the  the  imit.data  must  be  filled  out  prior 
to  this  call. 

assignfflent.key  can  be  used  to  record  an  initial  optimal  assignment  and  to  reuse  that  assign¬ 
ment  in  later  calls  to  formdb.ezpand. 

A  return  value  of  0  means  that  the  routine  succeeded.  A  return  value  of  -1  indicates  failure. 
The  only  source  of  failure  is  an  unrecognized  formation  name.  In  the  case  of  failure,  each  unit’s 
de8ired.position  will  be  equal  to  its  current.position,  and  nominal  values  will  be  supplied  for 
scan  sectors. 


2.3  formdb ^create jToutes 
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int32  formdb.create.routesCfornation.nane,  spacing,  n.units,  unit. data. 

input. route,  seunpling.distance, 
output. routes ,  input.f olloeing_unit , 
assignment.key) 
char  oformation.name; 

float64  spacing; 

int32  n. units ; 

FORMDB.DATA  unit.data[]; 

I10UTE.P0IHTS  •input. route: 
float64  sanpling.distance; 

R0UTE_P0INTS  output.routesG : 

int32  •input.following.unit: 

int32  assignnent.key: 

‘formation  name’ 

Specifies  the  name  of  the  formation.  This  should  be  a  Ubreader  symbol. 

‘spacing’  Specifies  a  desired  spacing  between  units,  in  meters 
‘n_ units’  Specifies  the  number  of  units  in  the  unit.data  array. 

‘unit.data’ 

Specifies  job  and  current  location  data  for  the  units.  The  return  fields  scanjccw  and 
scanxw  will  be  set. 

‘input. route’ 

Specifies  the  intput  route  as  an  ROUTEJ^OINTS  structure  (see  ‘stdroute.h’) 
‘8afflpling.di8tance’ 

Specifies  the  minimum  distance  between  points  in  the  input  route  that  will  be  used  to 
create  waypoints  for  the  output  routes. 

‘output.routes’ 

Returns  the  routes  that  all  the  units  in  the  unit.data  should  follow  to  stay  in  forma¬ 
tion.  On  input,  this  should  be  an  array  of  uninitialized  R0UTE_P0INTS.  On  output, 
this  array  will  contain  data  with  each  R0UTE_P0INTS  structure  containing  an  initial¬ 
ized  allocated  array  of  R0UTE.P0INT.  This  memory  must  be  deallocated  when  no  longer 
needed  via  STDDEALLOCCoutput.routeCi]  .points). 

‘input.folloving.unit’ 

Returns  the  index  into  the  unit.data  array  of  the  unit  which,  due  to  the  assignment 
of  units  in  a  formation,  cmild  follow  the  input  route  and  remain  in  formation.  If  no 
such  unit  exists,  -1  will  be  rctiirued. 

‘assignment.key’ 

Specifies  the  desired  job  |i<*.i(ion  relationships  (or  to  choose  an  optimal  relationship,  if 
-1) 


formdb.create.routes  applii-^  tb**  'pecificd  formation  and  spacing  to  the  units  in  unit.data 
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and  the  input.rout*  and  generates  output.routea  for  every  unit.  The  output  routes  will  be 
similar  to  the  input  joute  except  for: 

1.  route- point  displacements  to  account  for  station- keeping  offsets, 

2.  fewer  points  to  smooth  out  input  points  that  are  too  close  together  for  followers  to  check-point 
against.  Input  points  that  are  closer  co  each  other  than  sampling_di8tamca  will  be  ignored 
in  the  generation  of  the  output  routes. 

Every  R0UTE_P0INT  in  an  output  route  will  have  a  point.id  referring  to  one  of  the  original 
point.id  indices  in  the  input.route.  Note  that  this  routine  is  not  suitable  for  generating  road 
following  routes,  since  waypoints  for  followers  are  not  preserved. 

Formations  with  an  even  spread  and  an  odd  number  of  units  may  contain  a  unit  which  could  fol¬ 
low  the  input  route,  as  opposed  to  the  generated  output  route.  This  is  reported  in  iiiput_follo«ing.unit. 
Formations  with  an  even  number  of  vehicles  typically  generate  output  routes  which  straddle  the 
input  route  and  will  have  a  input_folloving_unit  of -1. 

A  return  value  >■  0  means  that  the  routine  succeeded,  and  indicates  the  assignment  order  which 
was  chosen  (see  Section  2.2  [formdb'expand],  page  7).  A  return  value  of  •!  indicates  failure.  The 
only  sources  of  failure  are  an  unrecognized  formation  name  or  an  input  route  that  is  contains  less 
than  two  waypoints.  In  the  case  of  failure,  the  output  routes  will  be  identical  to  the  input  routes, 
and  nominal  values  will  be  supplied  for  scan  sectors. 

Note  that  data  allocated  within  the  output  .routes  array  must  be  freed  when  no  longer  in  use. 


2.4  formdb.generate-roadmarch.x)rder 


void  foziiidb.generata.roadfflarch.order(n.units,  unit.data,  order. array) 
int32  n.units ; 

FORNDB.DATA  unit.data  □ ; 
int32  order.arrayD ; 

‘n.units’  Specifies  the  number  of  units  in  the  unit.data  array. 

‘unit.data’ 

Specifies  job  and  current  location  data  for  the  units.  The  return  fields  of  scanjccw  and 
scanjcw  will  be  filled  out. 

‘order.array’ 

Returns  the  order  of  march.  Each  element  of  this  array  is  an  index  into  the  imit.data 
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array. 

Given  unit.data,  fonBdb_gen«rate.roadffiarch_order  return  the  order  on  which  the  units 
should  follow  one  another  on  the  road.  This  is  currently  defined  as  the  preferred  column  order. 
The  order  of  march  is  defined  by  the  order  of  indices  returned  in  order.array. 


2.5  formdb-DCCupy-area 


void  formdb.occupy.areaCradius,  location,  n.units,  unit.data,  directions) 
f loat64  radius : 
float64  location [3] ; 
int32  n.units ; 

FORMDB.DATA  unit.dataC]: 
f loat64  directions [] ; 

‘radius’  Specifies  the  desired  radius  of  the  area 
‘location’ 

Specifies  the  desired  location  of  the  center  of  mass  of  the  formation.  If  it  is  equal  to 
[0.0,  0.0,  0.0],  then  the  center  of  mass  will  remain  unchanged. 

‘n_unit8’  Specifies  the  number  of  units  in  the  unit.data  array. 

‘unit.data’ 

Specifies  and  returns  data  for  the  units.  Desired  vehicle  plaurement  and  scan  sector 
information  will  be  returned  in  this  data. 

‘directions’ 

Returns  the  directions  that  each  unit  should  face. 


f  onsdb.occupy.arsa  returns  desired  positions  for  the  units  to  be  on  a  circle  of  a  given  raditu 
at  a  location  to  provide  for  all  around  security. 


2.6  formdbJierringbone 


void  foniidb_hsrringbons( spacing,  direction,  location,  n_unit8,  unit.data) 
float64  spacing; 

float64  direction; 

float64  location [3] ; 

int32  n. units ; 

FORMDB.DATA  imit.data[]; 
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‘spacing’  Specifies  a  desired  spacing  between  units,  in  meters 
‘direction’ 

Specifies  the  desired  direction  of  the  units  in  the  formation,  in  radians.  0  is  interpreted 
as  north,  and  directions  increase  positively  counter-clockwise. 

‘location’ 

Specifies  the  desired  location  of  the  center  of  mass  of  the  formation.  If  it  is  equal  to 
[0.0,  0.0,  0.0],  then  the  center  of  mass  will  remain  unchanged. 

‘n_unit8’  Specifies  the  number  of  units  in  the  unit.data  array. 

‘unit.data’ 

Specifies  and  returns  data  for  the  units.  Desired  vehicle  placement  and  scan  sector 
information  will  be  returned  in  this  data. 

f  ormdb.herringbona  returns  desired  positions  for  the  vehicles  to  get  off  of  the  road  from  column 
formation.  For  simplicity,  this  is  currently  modeled  just  as  a  staggered  column.  Because  there  is 
no  road  information  in  formdb,  there  is  no  guarantee  that  this  actually  gets  the  units  off  the  road. 
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1  Overview 


Libfwa  implements  an  instance  of  the  hull  class  of  components.  It  provides  a  low-fidelity  model 
of  fwa  vehicle  dynamics.  Capabilities  arc  modeled  only  to  the  second  order  (maximum  velocity, 
maximum  acceleration). 


The  parameters  of  a  fwa  vehicle  are  specified  in  its  configuration  Rle  as  follows: 


(f«a  (c_drag_sup«r  <float  >) 

(c_drag_8ub  <float  >) 

(vehlcla.naaa  <float>  kg) 

(thruat.min  <float>  H) 

(thrust.max  <float>  N) 

(llft.adn  <float>  N) 

(lift.maz  <float>  N) 

(aida.min  <float>  N) 

(sida.nax  <float>  N) 

(induced_drag_factor  <float>  ) 

(takeoff. alt  <float  ffl>) 

(speed.tau  <float  seO) 

(fpa.tau  <float  sec>) 

(track.tau  <float  seO) 

(roll.tau  <float  8ec>) 

(aoa.tau  <float  8ec>) 

(fuel.uaage  <float  kg/m>) 

(aixplane.drag. index  <float  >) 

( takeoff _8peed  <float  mp82>) 

(thrust.map  <chaTC32]  filename  ) 

(haxd_tuxn_rate  <float  portion  of  current  mazimuin>) 
(8tandard_tum_rate  <float  degree8/second>) 

(ea8y_tum.rate  <float  degree8/8econd>) 

(hard_climb_rate  <float  portion  of  current  mazimuffl>) 
(8tandard_climb.rate  <float  portion  of  current  maximuffl>) 
(easy.climb.rate  <float  portion  of  current  maximuffl>) 

(fuel.uaage  ;;  All  valuea  floata,  liat  in  increaaing  order 

(  <percent>  <percent>  ...) 

(<altitude>  <liter/sec>  <liter/sec>  ...) 

(<altitude>  <liter/8ec>  <liter/sec>  ...) 

(•••  •••  •••)) 


Applications  interface  to  the  fvsa  nnxlel  primarily  through  the  libhulls  interface.  The  most 
common  interface  for  controlling  \<'!in  motion  in  the  air  is  HULLS_SET_FLY_LEVEL.  Libfwa  will 
do  the  normalization  only  if  it  i'  i  for  example,  if  the  vehicle  is  already  pointing  the  right 

way,  no  normalization  is  nee<le«l  t. 
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Libfwa  supports  only  one  instantiation  per  vehicle  (i.e.,  a  vehicle  may  not  have  more  than  one 
fwa  hull). 


The  following  equations  describe  the  dynamics  of  the  fixed  wing  hull. 


air.dansity  ■  initial.air.density  •  exp(-Z/HR) 
initial.air. density  >  .0249 
HR  -  34.602.5  -  .14604Z 
Z  is  the  altitude  of  the  vehicle 

thrust  ■  (mass  «  gravity  *  sin(flight_path_ angle)  * 

mass  *  speed.rate.goal  ♦  drag) /cos (amgle.of .attack) 
track_force  ■  mass  *  (speed) ~2  *  cos (flight.path. angle)  * 
track_rate.goal 

fllght_path_angle.force  ■  mass  *  speed  * 

flight_path_angle_rate_goal 
mass  *  gravity  *  cos (flight.path. angle) 
roll.angle  «  arctan(track.force/flight_path.angle.force) 

normal  force  ■  sqrt (flight.path. angle.force‘2  ♦  track.force‘2) 
Coef.lift  «  21,522.3 

lift.goal  ■  normal.force  /  (1.0  ♦  (2.0  *  thrust)/ 

air.density  *  Coef.lift  ♦  8peed*2) 
angle.of.attack  •  2  *  lift.goal  / 

(air.density  *  speed‘2  *  Coef.lift) 
lift  •  (air.density  *  speed~2  •  Coef.lift  •  angle.of.attack) /2 


coef.sub.or.super  :  coef. drag. subsonic  when  speed  <  speed  of  sound 
:  coef.drag.8uper8onic  otherwise 
coef.drag  :  drag  coef  of  weapons  ♦  drag  coef  of  airplane 
drag  ■  air.density  *  speed^Z  *  coef.sub.or.super  e  coef.drag  + 
lift  *  angle.of.attack; 


8peed.rate  ■  (thrust  *  cos (angle.of.attack)  -  drag)  /  mass  *  gravity 
*  sln(flight.path.angle) ; 

fli^t.path.angle.rate  «  (lift  thrust  *  sin(angle.of.attack) 
cos(roll.angle)  side  *  sin(roll.angle)) /speed 
track.rate  ■  (lift  thrust  *  8in(angle.of. attack))  *  8in(roll.2mgle) 
/  mass  *  speed  *  cos (f light. path.angle) 


Applications  interface  to  the  fixed  wing  aircraft  (fwa)  model  primarily  through  the  libhulls 
interface.  The  libhulls  library  defines  a  common  set  of  functions  (and  the  semantics  of  those 
functions)  which  are  invoked  on  instances  of  the  hulls  class  (such  as  those  instantiated  by  libtracked, 
libfwa,  or  libmissile). 
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It  is  possible  to  modify  the  fwa  model  by  changing  an  exisiting  hulls  interface  function  or  by 

adding  a  completely  new  function.  To  modify  an  existing  hulls  interface  function  requires  the 

foUowing  actions: 

1.  If  the  change  occurs  only  in  the  function  body,  a  change  to  the  function  code  in  ihe  libfwa 
library  is  all  that  is  needed.  If  the  change  occurs  to  the  function’s  argument  list,  change  the 
function  code  in  the  libfwa  library  and  change  the  hulls  interface  structure  definition  found 
in  libhuUs.h.  Also  to  maintain  the  common  hulls  interface,  change  the  code  for  the  modified 
function  in  any  other  hull  specific  component  library  (such  as  libtracked  and  libmissile). 

2.  Recompile  ModSAF. 

To  add  an  additional  libfwa  function  to  the  current  model  requires  the  following  actions: 

1.  Write  the  function  as  part  of  the  libfwa  library.  The  function  is  written  in  the  code  which 
manages  the  libfwa  class  information  attached  to  each  vehicle  (fwajclass.c). 

2.  Add  the  function  and  its  declaration  to  any  of  the  other  huU  specific  component  libraries.  This 
maintains  the  common  hulls  interface. 

3.  In  the  libfwa  source  code  that  handles  libhull  initialization  processing,  include  a  f  unction_number , 
function  entry  identifying  the  new  function  for  the  capnt.def ine.instance  function  and  ev¬ 
ery  other  hull  instance  library  (libtracked,  libmissile,  etc  ) 

4.  In  libhuUs.h,  add  an  entry  to  identify  the  new  macro  and  associate  it  with  a  function  code 
number.  This  new  addition  means  that  the  number  of  hulls  functions  must  be  incremented  by 
one.  The  huUs  interface  structure  definition  that  appears  in  libhuUs.h  must  include  a  structure 
to  define  the  new  function’s  argument  list. 

5.  Recompile  ModSAF. 

To  replace  this  fwa  model  with  a  completely  different  one  requires  the  foUowing  actions: 

1.  Decide  on  the  get  functions  and  set  functions  that  would  be  required  in  the  new  model.  Try  to 
map  these  needed  functions  to  the  existing  hulls  interface.  A  function  can  map  if  its  argument 
Ust  can  remain  the  same.  Functions  that  can  not  map  must  be  added  to  the  huUs  interface. 

2.  For  those  functions  that  can  map  to  the  existing  huUs  interface  but  whose  code  body  you  want 
to  change,  edit  the  code  for  the  function  in  the  libfwa  source  file  that  contains  the  code  to 
manage  the  Ubfwa  class  information  (such  as  fwajclass.c). 

3.  For  those  functions  that  can’t  map  to  the  existing  hulls  interface,  add  an  additional  function 
to  the  hulls  interface.  The  addition  procedure  was  described  above. 

4.  Recompile  ModSAF. 
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If  an  interface  function  is  no  longer  needed,  it  is  possible  but  not  required,  to  remove  it.  Deletion 
of  an  interface  function  is  only  allowed  when  that  function  is  not  needed  in  any  of  the  specific 
component  libraries. 

The  deletion  process  requires  these  steps: 

1.  Delete  the  function  code  from  each  specific  component  library. 

2.  In  the  generic  component  library,  remove  the  "functionjiumber,  function"  entry  identifying 
the  excess  function  in  the  "cmpnt_defineJnstance"  function  call.  This  function  call  is  found  in 
the  library’s  initialization  code  segment.  In  the  library’s  public  header  file,  remove  the  entry 
for  the  excess  macro  and  its  associatiated  function  code  number.  Decrease  the  number  of 
interface  functions  by  one.  Delete  the  structure  that  defines  the  excess  function’s  argument 
list  in  the  interface  structure  definition. 

3.  Recompile  ModSAF. 
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2  Examples 

To  get  the  component  number  of  my  hull: 
extern  int32  my.hull; 

if  ((my.hull  ■  cmpnt_locate(vehicle_id,  reader.get.symbolC'hull")))  *• 
CMPNT.NOT.FOUND) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  hull\n",  vehicle.id) ; 

To  then  give  a  command  to  that  hull: 
if  (my.hull  !■  CMPNT.NOT.FOUND) 

HULLS_SET_DIRECTION.SPEED(vehicle.id,  hull,  dirvec,  speed,  0.0,  0.0); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libfwa,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  fwaJnit 


void  fwa_init() 


initializes  libfwa.  Call  this  before  calling  any  other  libfwa  functions. 


3.2  fwa_class Jnit 


void  fva_cla88.1nlt(parant_clas8) 
CLASS.PTR  parent.cla88 ; 


‘par«nt_cla88’ 

Class  of  the  parent  (declared  with  claaa.declare.claea). 

creates  a  handle  for  attaching  fwa  class  information  to  vehicles.  The  par- 
entjclass  is  one  created  with  classjdeclarejclass. 


3.3  fwa.tick 


void  fwa.tick(v8hicle_id,  ctdb) 
int32  vahicla.id; 

CTDB  *ctdb; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘ctdb’  Specifies  the  terrain  database 


fw*-tick  ticks  the  fwa  hull  dynamics  model. 
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3.4  fwa-collision 

void  fwa_colli8ion(vehicle_id,  position,  coll_t3rpe, 

other. id,  other.mass,  other. velocity) 

int32  vehicle.id; 
float64  position[3] ; 
uint32  coll.type ; 
int32  other.id; 
float64  other.mass; 
float64  other. velocity [3] ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘position’ 

Specifies  the  position  of  impact  in  world  coordinates 

‘coll.type’ 

Specifies  the  type  of  collision  these  values  are  defined  in  the  library  libcollision. 

‘other.id’ 

Specifies  the  vehicle  ID  of  the  other  party  (or  0  if  terrain) 

‘other  .mass’ 

Specifies  the  mass  of  the  other  party 
‘other. velocity’ 

Specifies  the  velocity  of  the  other  party 

f«a.colll8ion  tells  the  fwa  hull  dynamics  model  that  a  collision  occured.  The  coll_type  should 
be  one  of  the  libcollision  constants: 

COLL.TREES 

Indicates  crossing  a  treeline  or  canopy  edge. 

COLL.BUILDINGS 

Indicates  crossing  a  building  or  other  structure.  If  the  other  structure  is  represented 
on  the  network,  the  vehicle  ID  of  that  structure  should  be  provided. 

C0LL_GR0U11D 

Should  not  be  checked  for  ground  vehicles. 

C0LL.PLATF0RMS 

Indicates  intersecting  a  platform  (vehicle,  DI,  etc.). 

COLL.MISSILES 

Indicates  intersecting  a  missile  (an  entity  on  the  network  with  a  munition  type, 
f  ua.colli8ion  sets  the  vehicles  appearance  to  smoking  and  flaming.  If  the  collision  is  with  the 
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ground,  the  vehicles  appearance  is  also  set  to  destroyed. 


3.5  fwa_damage 

void  f«a_da]sage(vehicle_id.  damage) 
int32  vehicle.id; 
int32  damage; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘damage’  Specifies  whether  the  fwa  dynamics  should  simulate  being  damaged 

fwa.damage  tells  the  fwa  hull  dynamics  model  that  it  is  damaged  (or  not)  depending  on  the 
boolean  value  of  the  damage  flag. 
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1  Overview 


LibGenRadio  provides  rudimentary  radio  communications  to  ModSAF  entities.  It  allows  trans¬ 
mission  of  ASCII  strings  using  the  radio  protocols  of  SIMNET  and  DIS,  including  issuance  of 
transmitter  and  signal  PDU’s. 

Initially,  functionality  is  limited  to  vehicles  sending  brief  messages,  which  are  then  received  and 
displayed  by  the  GUI. 


1.1  Examples 

/*  currently  in  main.c  */  gradjnit(data_dir,  READER_OVERRIDE,  valve,  0); 

/*  currently  in  soJnit.c  */  grad-classJnit(safobj^lass); 

/*  currently  in  soJocal.c  */  gradjcreate(vehicleJd,  (GENRADIO-PARAMETRIC_DATA  *)parms); 
f*  currently  done  from  tasks  */  gradjsend.text(vehicleJd,  "Standing  by"); 


I*  currently  done  from  soJocal.c  */  grad.destroy(vehicleJd); 
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2  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libgenradio,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  gradJnit 


void  grad_init(data_dir.  flags,  valve,  protocol) 
char  *data_dir; 

uint32  flags ; 

PV_VALVE.PTR  valve; 
int32  protocol ; 


‘data.dir’ 

Path  to  data  files. 

‘flags’  Flags  to  pass  to  libreader. 

‘valve’  Libpktvalve  handle  to  use  for  network  access, 
‘protocol’ 

Protocol  version  in  effect  for  this  run  of  ModSAF. 


grad_init  initializes  LibGenRadio.  Call  this  before  any  other  libgenradio  function. 


2.2  grad -class  Jnit 


void  grad_cla8s.init(parent_class) 
CLASS.PTR  parent.class; 


‘parent.class’ 

Class  of  the  parent  (declared  with  class.declare.class) 

grad.cla88.init  creates  a  handle  for  attaching  genradio  class  information  to  vehicles.  The 
parent.class  will  likely  be  safobj. class. 
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2.3  grad-create 

void  grad_create(vehicle_id,  paraas) 
int  vehicle.id; 

GENRAOIO.PARAMETRIC.DATA  *paraas; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘pruraas’  Specifies  initial  parameter  values 

grad. create  creates  the  genradio  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


There  are  currently  no  parametric  data. 


2.4  grad^estroy 

void  grad. destroy (vehicle.id) 
int  vehicle.id: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

grad_de8tro7  frees  the  genradio  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.free.user.data. 


2.5  grad jsend-text 


void  grad.8end_tezt (vehicle.id,  string) 
int32  vehicle.id: 
char  ^string: 


‘vehicle.id’ 

Specifies  the  vehicle 

‘string’  Points  to  the  text  to  be  sent  over  the  radio. 
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grad.send.taxt  initiates  transmission  of  the  specified  text  over  the  vehicle’s  radio.  The  length 
of  the  string  sent  is  truncated  to  GRAD.MAX.MSG.LEN,  which  is  defined  in  libgenradio.h.  An  internal 
copy  of  the  text  is  maintained,  so  the  memory  indicated  by  string  may  safely  be  altered  or 
deallocated  any  time  after  this  function  returns. 


2.6  grad-subscribe 

void  grad.subscribe (vehicle. id,  message.queue) 
int32  vehicle. id; 

QUEUE.QUEUE  message.queue; 


‘vehicle.id’ 

Identifies  the  vehicle  containing  the  radio 
^ctdb’  Specifies  the  queue  for  incoming  messages 

grad.8ubscribe  requests  that  incoming  messages  be  enqueued  on  the  passed  queue.  The  mes* 
sages  are  placed  in  the  queue  using  a  GRAO.HESSAGE  structure: 


typedef  struct  grad_m«s8ag« 

uint32  time.received; 
int32  sender.id; 
char  text  □ ; 

}  GRAD.KESSAGE; 


Only  ModSAF  generated  ASCII  text  messages  will  be  enqueued. 


Libgenradio  will  take  care  of  the  deallocation  of  the  queue  when  the  vehicle  is  destroyed;  however, 
it  is  the  responsibility  of  the  caller  to  flush  any  messages  remaining  on  the  queue. 


2.7  grad_tick 


void  grad.tlckCvahicla.id,  ctdb) 
int32  vehicle.id; 

CTDB  *ctdb: 


’vehicle.id’ 

Identifies  the  vehicle  «ontaining  the  radio  to  be  ticked. 


6 


LibGenRadio  Programmer’s  Guide 


‘ctdb’  Specifies  the  terrain  database 

grad_tick  checks  radio  state  and  issues  PDU’s  as  required. 
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1  Overview 


Libgenturret  implements  an  instance  of  the  turret  class  of  components.  It  provides  a  low-fidelity 
model  of  generic  turret  dynamics  and  capabilities.  Turrets  that  can  not  support  360  degree  slewing 
(as  reported  in  libphysdb)  are  supported.  Turrets  can  be  described  as  having  either  a  continuous 
range  of  slew  rates  or  set  discrete  rates. 

The  parameters  of  a  generic  turret  are  specified  in  the  configuration  file  for  the  vehicle  containing 
such  a  turret  as  follows 

(generic-turret  (physdb-nane  <naae>) 

(rates  continuous  <nin-slea  deg/sec>  <Dax-slea  deg/sec>)) 

OR 

(generic-turret  (phsydb-naae  <name>) 

(rates  discrete  <ratel  slew  deg/seO 
<rate2  slew  deg/sec> 

<rate3  slev  deg/seO 

;;  rates  snist  be  monotonically  increasing 

...)) 

The  <naBe>  must  match  the  name  of  the  turret  as  specified  in  the  libphysdb  database.  The 
rates  are  in  degrees  per  second.  For  continuously  slewable  turrets,  the  minimnin  slew  rate  is  the 
slowest  the  turret  can  slew  without  stopping,  and  will  frequently  be  0.  For  discretely  slewable 
turrets,  the  rates  are  the  various  speeds  the  turret  can  slew. 

Applications  interface  to  the  generic  turret  model  primary  through  the  libturrets  interface.  The 
most  efficient  interface  for  controlling  turret  azimuth  is  TURRETS_SET.AZINUTH. 

Libgenturret  supports  up  to  4  instantiations  per  vehicle  (i.e.,  a  vehicle  can  have  up  to  4  generic 
turrets). 

The  libturrets  library  defines  a  common  set  of  functions  (and  the  semantics  of  those  functions) 
which  are  invoked  on  instances  of  the  turrets  class  (such  as  those  instantiated  by  libgenturret). 

It  is  possible  to  modify  the  generic  turret  model  by  changing  an  exisiting  turret  interface  function 
or  by  adding  a  completely  new  interface  function.  The  process  of  modification  of  an  existing 
libgenturret  function  is  fairly  simple  when  the  change  occurs  only  in  the  function  body.  In  that 
case,  the  programmer  would  only  need  to  change  the  function  code  in  the  libgenturret  library.  The 
process  of  modification  of  an  existing  libgenturret  function  is  more  complicated  when  the  change 
occurs  to  the  function’s  argument  list.  In  that  case,  the  programmer  would  need  to  change  both 
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the  function  code  in  the  libgenturret  library  and  the  turrets  interface  structure  definition  found  in 
libturrets.h.  Currently  libgenturret  is  the  only  turret  specific  component,  but  if  there  were  more, 
the  programmer  would  also  need  to  change  the  code  for  the  modified  function  in  those  libraries 
to  maintain  the  common  turrets  interface.  When  all  these  changes  have  been  made  to  the  source 
code,  ModSAF  would  need  to  be  recompiled. 

To  add  an  additional  interface  function  to  the  current  model,  a  programmer  would  need  to 
perform  the  following  actions: 

1.  Write  the  function  as  part  of  the  libgenturret  library.  The  function  is  written  in  the  code  that 
manages  the  libgenturret  class  information  attached  to  each  vehicle  (gtur.class.c). 

2.  Currently  libgenturret  is  the  only  turret  specific  component,  but  if  there  were  others,  the 
programmer  would  need  to  add  the  function  and  its  declaration  to  their  libraries  to  maintain 
the  common  turrets  interface. 

3.  In  the  libturrets  source  code  that  handles  libturrets  initialization  processing,  include  a  fimc* 
tion_number,  ftmction  entry  identifying  the  new  function  for  the  cBpnt.define.instanc* 
function. 

4.  In  libturrets.h,  add  an  entry  to  identify  the  new  macro  and  associate  it  with  a  function  code 
number.  Increment  the  number  of  turret  interface  functions  by  one.  Include  a  structure  to 
define  the  new  function’s  argument  list  in  the  turrets  interface  structure  definition. 

5.  Recompile  ModSAF. 

To  replace  this  genturret  model  with  a  completely  different  one  would  require  the  following 
actions: 

1.  Decide  on  the  interface  functions  that  would  be  required  in  the  new  model.  Try  to  map  these 
needed  functions  to  the  existing  turrets  interface.  A  function  can  map  if  its  argument  list  can 
remain  the  same.  Functions  that  can  not  map  must  be  added  to  the  turrets  interface. 

2.  For  those  functions  that  can  map  to  the  existing  turrets  interface  but  whose  code  body  you 
want  to  change,  edit  the  code  for  the  function  in  the  libgenturrets  source  file  that  contains  the 
code  to  manage  the  libgenturret  class  information  (gturjclass.c). 

3.  For  those  functions  that  can’t  map  to  the  existing  turrets  interface,  add  an  additional  function 
to  the  turrets  interface.  The  addition  procedure  was  described  above. 

4.  Recompile  ModSAF. 

Since  libgenturret  is  the  only  specific  turret  library,  it  would  be  safe,  but  not  required,  to 
remove  any  model  functions  that  are  no  longer  needed.  This  deletion  of  functions  would  be  more 
problemetic  if  there  were  multiple  turret  models.  In  that  case  it  would  be  necessary  to  check 


Chapter  1:  Overview 


6 


that  the  function  was  not  needed  in  one  of  the  other  specific  component  libraries.  To  remove  an 
unnecessary  libgenturret  function  from  the  current  model,  a  programmer  would  need  to  perform 
the  following  actions: 

1.  Delete  (or  comment  out)  the  function  code  from  the  libgenturret  library  (see  gtur_class.c).  If 
there  were  other  specific  turret  component  libraries,  the  function  would  be  deleted  from  those 
libraries  as  well. 

2.  In  the  libturrets  initialization  code,  remove  the  "function-number,  function"  entry  identifying 
the  excess  function  in  the  "cmpnt.iiofmeJnstance"  function  call. 

3.  In  libturrets.h,  remove  the  entry  that  identifies  the  excess  macro  and  its  associatiated  function 
code  number.  Delete  the  number  of  turret  interface  functions  by  one.  Delete  the  structure 
that  defines  the  excess  function's  argument  list. 

4.  Recompile  ModSAF. 
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2  Examples 


To  get  the  component  number  of  a  turret  with  a  particular  name  (such  as  "primary-turret"): 
int32  turret; 

if  ((turret  *  aq>nt_locate(vehicle_id,  name))  ■> 

CMPMT.HOT.FOUHD) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  turret  cabled  \"X8\".\n", 
vehicle. id, 
name) ; 


To  then  give  a  command  to  that  turret  (the  macro  is  defined  by  libturrets;  it  assembles  a 
TURRETS. INTERFACE  structure,  and  calls  cmpnt.invoke): 


if  (turret  !■  CMPHT.NOT.FQUND) 
TURRETS.SET.AZIMUTH(vehicle.id.  turret,  azinuth) ; 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libgenturret,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  generic-turretJnit 

void  generic.turret.initO 

generic.ttoret.init  initializes  libgenturret.  Call  this  before  calling  any  other  libgenturret 
functions. 


3.2  generic_turret.class Jnit 

void  genaric.turret.class.init (parent. class) 

CLASS.PTR  parent. class : 

‘parent. class’ 

Class  of  the  parent  (declared  with  class.declare.class). 

generic.turret.class.init  creates  a  handle  for  attaching  generic.turret  class  information  to 
vehicles.  The  parentjclass  is  one  created  with  classjdeclaire.class. 


3.3  generic-turret_tick 

void  generic.turret.tick(vehicle.id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 


generic.turret.tick  ticks  the  generic  turret  dynamics  model. 
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3.4  generic_turret-damage 

void  generic.turret.dafflageCvehicle.id,  daoage) 
int32  vehicle. id; 
int32  damage: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

’damage’  Specifies  whether  the  generic  turret  should  simulate  being  damaged 

generic.turret.damage  tells  the  generic  turret  model  that  it  is  damaged  (or  not)  depending 
on  the  boolean  value  of  the  damage  flag. 
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1  O  verv  ie  w 


LibGraphics  implements  a  C2  subclass  for  the  display  and  editing  of  persistent  objects.  It 
handles  the  display  of  points,  lines,  text,  and  taskframes,  and  the  editing  of  points,  lines,  and  text. 
Each  class  of  object  has  a  corresponding  sensitive  class,  which  is  used  when  the  graphic  is  displayed. 
LibGraphics  also  allows  other  libraries  to  register  their  own  sensitive  classes  which  are  used  when 
the  displaying  text  associated  with  objects  of  other  classes  (such  as  Units). 
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2  Usage 


The  software  library  ‘libgraphics.a’  should  be  built  and  installed  in  the  directory 
Vcommon/lib/’.  You  will  also  need  the  header  file  ‘libgraphics.h’  which  should  be  installed  in 
the  directory  VcoaiBon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make’ 
in  the  libgraphics  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on 
building  libgraphics. 


2.1  Building  Libgraphics 

The  libgraphics  source  files  are  found  in  the  directory  ‘/common/libsrc/libgraphics’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nf8/coinmon.8rc/libsrc/libgraphic8’. 

If  the  directory  ‘comaon/liberc/libgraphice’  does  not  exist  on  your  machine,  you  should  use 
the  ‘ganbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  common/libarc/libgraphica 

•  CO  RCS/*,v 

•  make  Install 

This  should  compile  the  library  ‘libgraphics.a’  and  install  it  and  the  header  file 
‘libgraphics  .h’  in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need 
to  adjust  the  source  code  or  ‘Naksf  ils’  for  the  platform  on  which  you  are  compiling,  libgraphics 
should  compile  without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libgraphics 

Libgraphics  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  *ld 
[source  .o  files]  -L/common/lib  -Igraphics  [other  libraries]’.  If  your  compiler  does  not 
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support  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/coomon/lib/libgraphics .  a’. 

Libgraphics  depends  directly  on  the  following  libraries:  libselect,  libprivilege,  libsafgul,  lib- 
tactmap,  libcoordinates,  libsensitive,  libeditor,  libreader,  lib  class,  and  libpo. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libgraphics,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  grph-init 

void  grph.initO 

grph_init  initializes  libgraphics.  Call  this  function  before  calling  any  other  libgraphics  func¬ 
tions. 


3.2  grph.create^ditors 


int32  grph_cr«ate.edltor8(data_path,  reader.f lags , 

gui,  tactaap.  tcc,  map.arass^c, 
sensitive,  refresh. event,  db,  select) 
*data.path; 
reader.flags; 
gui; 

tactaap; 
tcc; 

si^.erase_gc; 


char 

int32 

SGUI.PTR 

TACTMAP.PTR 

C00IU)_TCC.PTR 

GC 


SVSTVE.VIMDOV.PTR  sensitive; 
CALLBACK.EVEIfT_PTR  ref resh.event ; 
PO_DATABASE  *db; 

SELECT.TOOL.PTR  select; 


‘data_path’ 

Specifies  the  directory  wherr  data  files  are  expected 
‘reader.flags’ 

Specifies  flags  to  be  passed  to  reader  .read  when  reading  data  files 
‘gui’  Specifies  the  SAF  GUI 
‘tactaap’  Specifies  the  tactical  map 
‘tcc’  Specifies  the  map  coordinate  system 
‘aap.erase.gc’ 

Specifies  the  GC  which  can  erase  things  from  the  tactical  map 


6 


LibGraphics  Programmer’s  Guide 


’sensitive’ 

Specifies  the  sensitive  window  for  the  tactical  map 
‘refresh. event’ 

Specifies  the  event  which  fires  when  the  map  is  refreshed 
‘db’  Specifies  the  persistent  object  database 

‘select’  Specifies  the  select  tool 

grph_create_editors  creates  the  graphics  editors.  The  data  file  (‘graphics. rdr’)  is  read 
either  from  ‘.’or  the  specified  data  path,  depending  upon  the  reader.flags.  The  reader.flags 
are  as  in  reader.read.  The  return  value  is  zero  if  the  read  succeeds,  or  one  of  the  libreader  return 
values:  11EADER.REA0_ERR0R,  READER.FILE.NOT.FOUND. 


3.3  grph-register-association 

void  grph_rsgister_association(gui,  po.class,  snstvs.class) 

SGUI.PTR  gui; 

PsrsistsntObjactClass  po.class; 

SHSTVE.CLASS  *snstvs.class ; 

‘gui’  Specifies  the  SAF  GUI 
‘po.class’ 

Specifies  the  persistent  object  class  (objectClassUnit,  etc.) 

‘snstvs.class’ 

Specifies  the  sensitive  class 

grph.rsgistsr. association  tells  the  graphics  editors  the  sensitive  class  which  should  be  used 
when  displaying  text  associated  with  objects  of  the  specified  PO  class.  This  should  be  called  after 
all  graphics  editors  have  been  created. 


3.4  grph. edit  .text 


void  gzph.adit. text (gui,  id) 
SGUI.PTR  gui; 

ObjactID  *id; 


‘gui’ 


Specifies  the  GUI 
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‘id’  Specifies  the  ID  of  the  text  to  edit 

grph.adit.tezt  starts  up  the  text  editor  for  the  passed  text  object.  This  function  is  provided 
to  allow  editing  of  the  text  associated  with  an  object.  Note  that  the  caller  is  responsible  for  making 
sure  the  GUI  is  in  a  state  where  the  text  editor  can  be  started  (i.e.,  another  OBJECT.MODE  editor  is 
not  running). 


3.5  grph^class Jnit 

void  grph.clasB.init(parant.claas) 

CLASS.PTR  parent. claaa : 

‘parent.clans’ 

Specifies  the  parent  class  (probably  c2obj .class) 

grph.class.init  creates  a  handle  for  attaching  graphics  class  information  to  entries.  The 
paront.class  is  one  created  with  class.daclara.class. 


3.6  grph-create 

void  grph.create (entry) 

PO.DB.EKTRY  eentry; 

‘entry’  Specifies  the  graphic  entry 

grph.creato  creates  the  graphics  class  information  for  a  entry  and  attaches  it  to  the  entry’s 
libclass  user  data.  This  function  simply  returns  if  no  graphics  editors  have  been  created  (running 
without  a  GUI),  or  the  entry  is  not  of  a  class  for  which  libgraphics  is  responsible. 


3.7  grph-destroy 

void  grph.dostroy (entry) 
PO_DB.EITRY  eentry; 


‘entry’  Specifies  the  graphic  entry 
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grph_de>tro7  frees  the  graphics  class  information  for  a  entry. 


3.8  grph-changed 

void  grph. changed (entry) 

PO.DB_EIITRy  eentry; 

‘entry’  Specifies  the  graphic  entry 

grph.  changed  updates  displayed  graphic  in  response  to  a  libpo  object  .changed  event. 


3.9  grph_overlay .changed 

void  grph.overlay_changed(entry} 

PO.DB.EirrRY  aentry; 

‘entry’  Specifies  the  graphic  entry 

grph.overlay. changed  updates  displayed  graphic  in  response  to  a  libpo  object. changed  event 
for  the  graphic’s  overlay. 
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1  Overview 


Guns  is  a  SAP  components  class.  The  purpose  of  a  components  class  is  to  define  a  common 
set  of  functions  which  are  invoked  on  instances  of  that  class,  and  the  semantics  of  those  functions. 
Other  than  defining  these  functional  semantics,  components  classes  don’t  actually  *do*  anything. 

Access  to  gun  functions  is  achieved  through  macros  defined  by  libguns.  These  macros  invoke 
‘cmpntJnvoke’  with  a  code  number  which  identifies  the  function  to  run.  Libcomponents  then  runs 
this  function  for  the  particular  gun  mode  via  a  jump  table. 

The  table  below  shows  how  the  gun  component  relationships  have  been  currently  implemented 
via  the  ModSAF  library  structure. 

specific  libraries  generic  library  architectural  library 

libbalgun  libguns  libco^onents 

libnlatmcher  libguns  libcosiponents 

As  mentioned  above,  libguns  requires  the  services  of  libcomponents,  an  architectural  library 
which  provides  a  level  of  abstraction  away  from  the  specific  gun  component  interfaces.  When  the 
ModSAF  application  gets  set  up  to  run,  the  libguns  initialization  process  directs  libcomponents 
to  define  a  gun  component  class.  This  information  enables  libcomponents  to  define  a  structure 
to  accommodate  all  of  the  gun  instantiations  a  simulated  object  is  allowed  to  have.  The  libguns 
initialization  process  also  tells  libcomponents  the  number  of  its  defined  gun  interface  functions. 
This  enables  a  simulated  object’s  user  data  to  be  allocated  enough  space  to  hold  the  address  of 
each  of  the  interface  functions  defined  in  libguns. 

The  parametric  data  of  libcomponents  identifies  each  component  that  needs  to  be  modeled  when 
a  vehicle  is  simulated.  For  example,  a  component  entry  for  a  T72  tank  might  look  like  this:  (see 
the  file  named  USSR.T72M4>arams.rdr) 

(SN.Componentn  (hull  SN.TrackedHull} 

(turret  SN.GenericTurret) 

(suchine'gun  [SM.BallisticGan  I  0]) 

(main-gun  [SN.BallisticGun  I  1]) 

(visual  SN.Visual)) 

A  T72M  simulated  vehicle  (which  belongs  to  the  safobj  class)  will  have  component  sub>clas8  data 
which  tells  the  ModSAF  software  to  maintain  a  structure  that  includes  one  libbalgun  instantiation 
for  the  machine  gun  and  one  libbalgun  instantiation  for  the  main  gun. 
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Since  an  application  will  interface  to  libbalgun  or  libmlauncher  through  libguns,  a  tank’s  main 
gun  shooting  control  commands  (which  are  performed  by  libbalgun)  and  an  airplane’s  missile 
launcher  commands  (which  are  performed  by  libmlauncher)  are  both  issued  via  the  interface  defined 
by  libguns.  A  command  to  load  ammunition  is  therefore  the  same  whether  the  object  is  loading  a 
main  gun,  machine  gun,  or  missile  launcher.  What  is  different  is  the  type  or  ammunition  to  load  and 
that  is  passed  as  input  to  the  gun  function.  Similarly,  an  application  can  obtain  information  about 
the  state  of  any  of  its  guns  though  the  libguns  interface.  The  table  below  shows  the  relationship 
between  the  specific  and  generic  library  for  the  guns  component. 

Instantiations  of  Belong  to  generic  Have  a  command 

of  the  library:  component  class:  interface  defined  in: 


libbalgun  guns  libguns 

libsdauncher  guns  libguns 

The  interface  to  libguns  is  defined  in  its  public  header  file  (libguns.h).  This  interface  lets  an 
application  set  gun  controls  or  get  gun  information  without  knowing  which  specific  gun  model  is 
being  used.  Applications  interface  to  the  ballistic  gun  model  or  missile  launcher  model  primarily 
through  the  macros  defined  in  libguns.  These  macros  map  to  functions  which  are  invoked  on 
instances  of  the  guns  sub-class  (such  as  the  libmlauncher  component  instantiated  for  an  airplane 
or  the  libbalgun  component  instantiated  for  a  tank). 

One  interface  for  controlling  a  gun  is  the  macro  GUNS.SET.UNLOAD.HUNITIOH  which  maps  to  a 
function  which  starts  the  procedure  of  transfering  a  given  number  of  loaded  munitions  to  a  storage 
bin.  A  possible  definition  for  this  macro  is  shown  below. 

•define  GUNS_SET_UNLOAD_NUNITIOM(_vid,  .cnum,  .store,  .quantity) 
GUHS.INTERFACE  .gif; 

.gif .u. set. unload.munit ion. store  *  .store; 

_gif.u.8et_unload_munition. quantity  *  .quantity; 

cmpnt_invokaCGUlfS.SET.UNLOAD.NUlfITIOR.FCH,  .vid,  .cnum,  (A0DRESS)ft_gif ) ; 

} 

The  GUHS.INTERFACE  structure  defined  in  libguns.h  is  the  structure  which  is  passed  to  any  gun 
function.  This  structure  is  a  union  of  structures  that  each  define  an  argument  list  for  a  gun  interface 
function.  An  abbreviated  example  that  assumes  there  are  only  two  gun  functions  is  shown  below. 
Typically  there  will  be  many  interface  functions  and  therefore  more  structure  definitions  in  the 
union.  The  macros  hide  this  structure  from  the  users  of  these  functions. 


typedef  struct  guns .interface 
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{ 

union 

{ 

struct  guns.set.unload.munition 

int32  store; 
int32  quantity: 

}  set_unload_munition; 
struct  guns_get_loaded_munition 

uint32  munition; 

int32  quantity; 

>  get_loaded_nunition; 

>  u; 

}  GUNS.INTERFACE; 


Issuing  a  command  to  an  objects ’s  gun  component  is  done  by  invoking  one  of  the  macros  defined 
in  libguns.  These  macros  identify  the  specific  component  function  which  needs  to  be  called.  For 
example,  invoking  the  GUVS.SET.URLQAO.MUHITIOR  macro  will  result  in  the  calling  of  the  specific 
component  function  named  set.unloa<Lmunition.  In  the  public  header  file  of  each  generic  library, 
macros  are  associated  with  a  function  code  number  so  that  a  call  to  the  libcomponents  library 
(via  the  cmpntJnvoke  function)  will  dispatch  a  call  to  the  appropriate  function.  The  specific 
component  functions  are  defined  and  installed  by  the  specific  libraries  (libbalgun  and  libmlauncher). 
In  this  case,  both  libraries  install  a  function  with  the  same  name,  ''setjunload-munition''  (there 
is  no  name  conflict  because  each  function  is  declared  static).  It  is  the  specific  function  (either 
libbalgim’s  set_unload^unition  or  liblmauncher’s  setjunloadununition)  which  is  called  when  the 
macro  is  invoked. 

Invoking  the  macro  results  in  two  actions:  (1)  setting  up  of  the  interface  structure  and  (2) 
passing  of  necessary  information  to  libcomponent.  The  macro  passes  the  vehicle  id,  component 
number,  and  function  pointer  index  to  libcomponent  so  that  the  appropriate  library  (libbalgun  or 
libmlauncher)  data  can  be  accessed.  The  requested  function  can  require  input  (such  as  a  storage 
bin  to  unload  the  munition  into  and  a  quantity  to  transfer  into  the  storage  bin)  and/or  output 
(such  as  a  setting)  .  Therefore,  libcomponents  must  also  be  passed  the  address  of  the  interface 
structure  that  holds  this  data. 
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2  Examples 


To  initialize  libbaJgun.  an  instance  of  the  gun  class  which  provides  for  up  to  BGUN.MAX.GUNS 
guns  per  entity; 


int32  i; 
char  buf [256] : 

for  (i  ■  0;  i  <  BGUN. MAX .GUNS; 

•C 

(void)  aprintfCbuf,  "gunXd",  i); 
bgun.user.data.handlaCi]  ■ 

class.reaerve.user.dataCparent.class.  buf,  bgun.print); 

} 

/*  Tell  libcomponants  ee  are  available.  *! 
aBpnt_define.in8tance(SM.Balli8ticGu&,  BGUN.MAX.GUNS, 

bgun.user.data.handle , 
bgun.create,  bgun.destroy , 

GUNS.GET.NAGAZINE.SIZE.FCN,  get.magazine.size, 

GUN? .SET.LOAD.MUNITION.FCH ,  aet.load.munition , 

GUNS.SPT.  TLOAD.MUNITION.FCN ,  8et.unload.munition, 
GUN?..G^  ,  '4DED.MUHmON_FCH,  get.loaded.munition, 
GUNS.SLT  '.aUNCHER.POSITION.FCN , set. launcher .posit ion , 
GUNS.CET.LAUNCHER.POSITI ON.FCN , get .launcher.pos it ion , 
GUNS.SET.ELEVATION.FCN ,  set.elevation , 
GUNS.SET.TARGET.FCN,  set. target, 

GUNS.SET.LOCATION.FCN ,  set. location , 
GUNS.GET.TARGET.IS.TRACKED.FCN,get.targot.i8.tracked, 
GUHS.GET.LOCATIOH.IS.TRACKED.FCN , 
get.location.is.tracked , 

GUNS.GET.READY_TO_FIRE.FCN,  get.ready.to.fire, 
GUNS.GET.NUNITION.READY.FCN ,  get.niunition.ready . 
GUNS.SET.FIRE.FCH,  set.fire, 

GUNS.SET.FIRE.AT.TARGET.FCN ,  set. fire.at. target , 
GUMS.SET.FIRE.AT.LOCATION.FCN ,  set.f ire.at.location, 
GUNS.GET.ALLOUEO.MUNITIONS.FCN,  get.alloved_munition8) ; 


To  get  the  component  number  of  a  gun  with  a  particular  name  (such  as  "main-gun"): 


int32  gun; 

if  ((gun  ■  cnpnt.locatef vehicle. id,  naae))  » 

CMPNT.NOT.FOUND) 

printf ("Vehicle  Xd  does  not  sees  to  have  a  gun  called  \"Xs\".\n", 
vehicle. id, 
nane) ; 
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To  then  give  a  command  to  that  gun  (the  macro  is  defined  by  libguns;  it  assembles  a  GUNS.IITTERFACE 
structure,  and  calls  cn^nt.invoke): 

if  (gun  !■  CMPHT.HQT.FOUND) 

GUNS.SET.ELEVATION (vehicle. id,  gun,  elevation); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libguns,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  gunsJnit 

void  guns.initO: 

guns.init  initializes  libguns.  Call  this  function  after  cmpnt.init,  and  before  any  specific  gun 
init  functions. 


3.2  GUNS.GET_MAGAZINEJSIZE 


void  GUNS.GET.MAGAZINE.SIZEC.vid,  .cnufli,  .quantity) 
lnt32  .vid; 
int32  .cnum; 
int32  ♦.quantity; 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.quantity’ 

Returns  the  maximum  magazine  size  of  munitions  loadable 


GUNS.GET.MAGAZIME.SIZE  returns  (by  reference)  the  maximum  magazine  of  munitions  that  can 
be  simultaneously  loaded  into  the  gun. 


3.3  GUNSJSET_LOAD_MUNITION 


void  GUNS.SET.LOAD.HUNITlONC.vid,  .cnum,  .munition,  .store,  .quantity) 
int32  .vid; 
int32  .cnum; 
int32  .store; 
uint32  .munition; 
int32  .quantity; 
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‘_vid’  Specifies  the  vehicle  ID 

’.cnim’  Specifies  the  gun  component  number 

‘.■unit  ion’ 

Specifies  the  type  of  munition  to  load 
‘.store’  Specifies  from  what  store  to  load  the  munition  from 
‘.quantity’ 

Specifies  the  quantity  of  munitions  to  load  into  the  gun 

GUNS.SET.LOAD.MUNITION  starts  the  loading  procedure  of  a  number  of  munitions  from  the 
supplied  store.  Illegal  requests  to  load  too  many  munitions  will  be  clipped  to  legal  amounts. 


3.4  GUNSJSET-UNLOAD_MUNITION 

void  GUNS.SET.UNLQAD.NUNITIONC.vid,  .cnum,  .store,  .quantity) 
int32  .vid; 
int32  .cnum; 
int32  .store; 
int32  .quantity ; 

‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.store’  Specifies  into  what  store  to  unload  the  munition  into 

‘.quantity’ 

Specifies  the  quantity  of  munitions  to  unload  from  the  gun 


GUNS.SET.UNLOAD .MUNITION  starts  the  unloading  procedure  of  a  number  of  already  loaded  mu¬ 
nitions  into  the  supplied  store.  Illegal  requests  to  unload  too  many  munitions  will  be  clipped  to 
legal  amounts. 


3.5  GUNS-GET-LOADED-MUNITION 


void  GUNS.GET.LOADED.HUNITIONC.vid,  .cnum,  jmmition,  .quantity) 
int32  .vid; 
int32  .cnum; 
uint32  ^.munition; 
int32  ^.quantity; 
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‘.▼id’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.munition’ 

Returns  the  loaded  munition 

‘.quantity’ 

Returns  the  loaded  quantity 

GUNS.GET.LOADED.KinilTIQN  returns  (by  reference)  the  quantity  and  munition  loaded  in  the 
gun. 


3.6  GUNSJSET-LAUNCHER-POSITION 

void  GUHS.SET.LAUNCHER.POSZTION(.vid.  .cnum.  .active) 
int32  .vid; 
int32  .cnum; 
int32  .active ; 

‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.active’  Specifies  whether  to  set  the  launcher  active  or  not 

GUHS.SET.LAUHCHER.POSITION  starts  process  of  putting  gun  in  active  or  inactive  position  based 
on  the  boolean  value  of  active.  For  things  like  a  TOW  missile  launcher  or  a  LOSAT  mast  launcher, 
this  may  take  some  time  and/or  result  in  appearance  modifiers  chan^ng  in  the  entity.  A  gun  must 
made  active  before  it  is  ready  to  fire. 


3.7  GUNS-GET JiAUNCHERJOSITION 


void  GUMS.GET.UUNCHER.PQSITI01l(.vid.  .cnum.  .active) 
int32  .vid; 
int32  .cnum; 
int32  e.active; 


‘.vid’ 

‘.cnum’ 


Specifies  the  vehicle  ID 

Specifies  the  gun  component  number 
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‘.active’  Returns  current  state  of  gun  position 


GUNS.GET.LAUNCHER.POSITION  retrieves  state  of  gun  launcher.  This  returns  TRUE  if  the  gun  has 
only  one  position  or  if  the  gun  is  in  the  firing  position. 


3.8  GUNSJSET-ELEVATION 


void  GUMS_SET_ELEVATIOM(.vid,  .cnua,  _el) 
int32  _vid; 
int32  _cnum; 
int32  _el ; 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnuffl’  Specifies  the  gun  component  number 

‘.el’  Specifies  the  desired  elevation 

Certain  guns  (such  as  a  tank  main  gun)  can  be  elevated.  For  those  guns,  GUNS.SET.ELEVATIOH 
will  select  a  desired  elevation  for  that  gun.  If  the  gun  does  not  support  elevation,  this  will  not  do 
anything.  If  the  requested  elevation  is  not  possible,  the  requested  elevation  will  be  clipped  to  a 
legal  value. 


Setting  the  elevation  of  the  gun  automatically  takes  the  gun  out  of  the  target  tracking  mode 
(see  Section  3.9  [GUNS'SET'TARGET],  page  10)  or  location  tracking  mode  (see  Section  3.10 
[GUNS -SET-LOCATION],  page  11). 


3.9  GUNSJ5ET-TARGET 


void  GUHS.SET.TARGETC.vid,  .cnua,  .targetid) 
int32  .vid; 
int32  .cnua; 
int32  .targetid 


‘.vid’  Specifies  the  vehicle  M) 

‘.cnum’  Specifies  the  gun  r<>tii|M>n<'nt  number 

‘.targetid’ 

Specifies  the  id  of  the  (arget  to  track 
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GUNS.SET.TARGET  puts  the  gun  in  an  automatic  mode  where  the  gun  will  attempt,  through 
use  of  the  gun’s  turret  component,  to  track  on  the  targetid.  Note  that  if  the  gun’s  turret  is  not 
slewable,  this  may  not  do  anything. 

Setting  the  elevation  of  the  gun  (see  Section  3.8  [GUNS’SET’ELEVATION],  page  10)  automat¬ 
ically  takes  the  gun  out  of  this  target  tracking  mode. 


3.10  GUNSJSETJLOCATION 


void  GUMS_SET_L0CATI0N(_vid,  _cnuB»  .location) 
int32  .vid; 
int32  .cmm: 
floated  .location [3] : 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.location’ 

Specifies  the  location  to  track 


GUNS.SET.LOCATION  puts  the  gun  in  an  automatic  mode  where  the  gun  will  attempt,  through 
use  of  the  gun’s  turret  component,  to  track  on  the  location.  Note  that  if  the  gun’s  turret  is  not 
slewable,  this  may  not  do  anything. 


3.11  GUNS_GET_TARGETJ[S_TRACKED 


void  GUHS.GET.TARGET.IS.TRACKED(.vid,  .cnna,  .targatid,  .result) 
int32  .vid; 
int32  .cnun; 
int32  .targatid; 
int32  a.rasult ; 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.targatid’ 

Specifies  the  id  of  the  target  to  track 
‘.result’  Returns  whether  the  target  is  tracked 
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GUHS_GET_TARGET_IS_TRACKED  returns  (by  reference)  whether  the  vehicle  .targetid  is  success¬ 
fully  tracked  by  the  gun. 


3.12  GUNS_GET_LOCATION_IS_TRACKED 

void  GUHS_GET_LOCATIOH_IS.TRACKED(_vid,  _cnua,  .location,  .result) 
int32  .vid; 
int32  .cnua; 
int32  .location: 
int32  e.rasult ; 

‘.vid*  Specifies  the  vehicle  ID 

‘.cnun’  Specifies  the  gun  component  number 

‘.locat 

.specifies  the  location  to  track 
‘.result’  Returns  whether  the  location  is  tracked 

GUNS.GET.LQCATIOK.IS.TRACKED  returns  (by  reference)  whether  the  position  .location  is  suc¬ 
cessfully  tracked  by  the  gun. 


3.13  GUNS_GET_READY_TO_FIRE 

void  GiniS.GET.READY.TO.FIREC.vid,  .cnua,  .ready,  .id) 
int32  _vid; 
int32  .cnua; 
int32  e.ready; 
int32  *_id; 

‘.vid’  Specifies  the  vehicle  ID 

‘.cnua’  Specifies  the  gun  component  number 

‘.ready’  Returns  whether  the  gun  is  ready  for  firing 
‘.id’  Returns  vehicle  ID  of  ready  missile 

GUIS.GET.REAOY.TO.FIRE  returns  (by  reference)  whether  the  gun  is  ready  to  fire.  For  missile 
launchers,  the  vehicle  ID  of  the  ready  missile  is  returned  (by  reference)  as  well.  The  gun  is  generally 
not  ready  if  it  is  not  loaded  or  is  in  the  process  of  loading  or  unloading  mumtions. 


a  ^ 
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3.14  GUNSJ5ET_FIRE 


void  GUHS_SET_FIRE(_vid,  .cnuai,  .quantity) 
int32  _vid; 
int32  .cnua; 
int32  .quantity: 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnua’  Specifies  the  gun  component  number 

‘.quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 


GUHS.SET.FIRE  launches  a  weapon.  The  weapon  is  fired  in  whatever  direction  it  is  currently 
pointing.  If  the  weapon  is  not  loaded,  this  will  do  nothing.  If  .quantity  specifies  an  amount 
greater  than  that  currently  loaded  by  the  gun,  the  amount  will  be  clipped  down  to  the  loaded 
amount. 


3.15  GUNSJSET-FIRE^T-TARGET 


void  GUVS_SET.FIRE.AT_TARGET(_vid,  .cnua,  .quantity,  .targatid) 
int32  .vid; 
int32  .cnua; 
int32  .quantity: 
int32  .targatid; 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnua’  Specifies  the  gun  component  number 

‘.quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 


‘.targatid’ 

Specifies  the  target  to  fire  at 


GUIIS.SET_FIRE.AT.TARGET  launches  a  weapon  at  .targatid.  K  the  weapon  is  not  tracked  on 
the  target,  this  will  most  likely  miss  the  target.  U  the  weapon  is  not  loaded,  this  will  do  nothing, 
.quantity  specifies  an  amount  greater  than  that  currently  loaded  by  the  gun,  the  amount  will 
clipped  down  to  the  loaded  amount. 
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3.16  GUNS^ET-FIRE^T-LOCATION 


void  GUNS_SET_FIRE_AT_LQCATION(_vid,  .cnuB,  .quantity,  .location) 
int32  .vid; 
int32  .cnun; 
int32  .quantity; 
float64  .location[3] ; 


‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  gun  component  number 

‘.quantity’ 

Specifies  quantity  of  loaded  munition  to  shoot 

‘.location’ 

Specifies  the  location  to  fire  at 


GUNS.SET.FIRE.AT.LOCATION  launches  a  weapon  at  .location.  If  the  weapon  is  not  tracked 
on  the  location,  this  will  most  likely  miss  the  location.  If  the  weapon  is  not  loaded,  this  will  do 
nothing.  If  .quantity  specifies  an  amount  greater  than  that  currently  loaded  by  the  gun,  the 
amount  will  be  clipped  down  to  the  loaded  amount. 


3.17  GUNS_GET_ALLOWED_MUNITIONS 

void  GUMS.GET.ALLOWED.NUNITIOlfSC.vid,  .cnun,  .nun,  jnunitions, 

.cur,  .aba) 

int32  _vid; 

int32  .cnun; 

int32  *.nun; 

GUlfS.NUllITIOIS  .nunitiona; 

GUHS.QUAITITIES  .cur; 

GUIS.qUAHTITIES  .aba; 

‘.vid’  Specifies  the  vehicle  ID 

‘.cnun’  Specifies  the  gun  component  number 

‘.nun’  Returns  the  length  of  the  Ust  (<=  GUNS  JlAXJdUNITIONS) 
‘jmmitiona’ 

Returns  the  list  of  allowed  munitions 
‘.cur’  Returns  the  list  of  current  limits  on  munition  quantities; 

‘.aba’  Returns  the  list  of  absolute  limits  on  munition  quantities; 
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GUNS. GET. ALLOWEO.HUMITIONS  returns  (by  reference)  a  list  of  munitions  which  can  be  loaded 
in  the  gun.  The  data  is  returned  in  a  GUNS.MUNITIONS  data  structure  which  is  declared  as  follows: 

typedef  uint32  GUNS.MUNITIONS [GUNS.MAX.NUNITIONS] ; 

In  addition,  two  lists  of  quantities  are  returned  (by  reference.)  One,  is  the  list  of  quantities  of 
munitions  which  the  gun  currently  can  fire,  one  is  the  list  of  maximum  quantities  of  munitions  the 
gun  can  fire.  Both  of  these  are  based  on  internal  limitations  of  the  gun  implementation  and  may 
not  be  equal  to  the  supplies  of  the  munitions  available  to  the  vehicle. 

The  lists  of  quantities  are  returned  in  a  GUNS.QUANTITIES  data  structure  which  is  declared  as 
follows: 

typedef  int32  GUNS.QUANTITIES [GUNS.HAX.MUNITIONS] ; 


The  current  value  of  GUNS.HAX.MUNITIONS  is  4. 
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1  Overview 


LibHM  provides  utility  functions  for  managing  Height/Much  (HM)  diagrams.  The  library  con¬ 
tains  an  editor  ‘hnedit’,  which  can  be  used  to  generate  a  thrust  map,  which  is  a  generalization 
about  engine  capabilities  which  can  be  derived  from  an  HM  diagram. 

The  library  contains  the  tool  make_uu,  which  takes  a  new  .map  hie,  and  uuencodes  it  so  it  can 
be  stored  and  used  by  res.  .uu  versions  of  the  .map  file  are  converted  by  the  makefile  back  to  the 
.map  format. 

The  library  provides  functions  for  reading  these  thrust  maps,  and  accessing  the  information 
therein.  It  also  provides  utility  functions  for  computing  air  density  and  true  mach  number. 


1.1  Examples 


The  following  code  fragments  from  a  version  of  libFWA,  demonstrate  usage: 


/*  Read  the  thrust  map  */ 

fea->thru8t.inap  ■  hD_get_thru8t_map(parais8->thru8t.map) ; 


current_thru8t_max  ■  hm_thrust(fea->thru8t_nap, 

f«a->po8ition[Z] , 
fva->8peed. actual) ; 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libhm,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  hmJnit 

void  hiii_init(data_directory) 
char  *data_diroctory; 

‘data. directory’ 

Specifies  the  directory  where  thrust  maps  are  expected 

hm  init  initializes  libhm.  The  passed  data  directory  will  be  used  when  reading  thrust  maps,  if 
the  named  files  cannot  be  found  in 


2.2  hm .get.thrust jnap 

HM.THRUST_HAP.PTR  ta]ii_get_thrust_map(file_name) 
char  efile.name; 

‘file.name’ 

Specifies  the  file  in  which  the  thrust  map  is  stored 

h]B.get.thrust.i&ap  returns  the  thrust  map  stored  in  the  name  file.  Note  that  the  data  is 
cached  so  that  future  references  to  the  same  file  will  return  the  same  pointer.  A  NULL  return  value 
indicates  an  error  occured. 


2.3  hm-thrust 

float64  ha. thrust (thrust. sap,  altitude,  velocity) 
HM_THRUST.MAP.PTR  t. ‘trust. sap; 
float64  altitude; 

float64  velocity: 
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‘thrust.map’ 

Specifies  the  thrust  map  (created  by  ha_get.thrtiat_inap) 

’altitude’ 

Specifies  current  altitude  (meters) 

‘velocity’ 

Specifies  current  speed  (meters/second) 

hnu, thrust  looks  up  the  maximum  thrust  available  (in  Newtons)  given  the  passed  altitude  and 
velocity. 


2.4  hm-power 


float64  hm_ poser (thrust.map,  altitude,  velocity,  mass,  drag) 
HM_THRUST_MAP.PTR  thrust.map; 
f loat64  altitude ; 

float64  velocity; 

float64  mass; 

float64  drag; 

‘thrust.map’ 

Specifies  the  thrust  map  (created  by  hm.get.thrust.map) 

‘altitude’ 

Specifies  current  altitude  (meters) 

‘velocity’ 

Specifies  current  speed  (meters/second) 

‘mass’  Specifies  current  vehicle  mass  (kilograms) 

‘drag’  Specifies  current  drag  (newtons) 


hm.pover  looks  up  the  avmlable  power,  given  the  altitude  and  velocity  (which  me  used  to 
determine  thrust),  and  mass  and  drag. 


2.5  hm^irudensity 

float64  hm_air.density(altitude} 
float64  altitude; 


Chapter  2:  Functions 


5 


‘altitude' 

Specifies  an  altitude  (meters) 

hiB_air_density  computes  the  air  density  at  a  passed  altitude. 


2.6  hmjair^ensity_rat_sq 

float64  hm_air_dan8ity_rat_8q(altitud6) 
float64  altitude; 


‘altitude’ 

Specifies  an  altitude  (meters) 

h]B_air_den8ity_rat.aq  returns  the  square  of  the  ratio  of  air  density  at  an  altitude  to  air 
density  at  sea  level  (needed  in  some  equations).  Equivalent  to 

8quare(hiii_air.den8ity(altitude)/ha.air_den8ity(0.0)),  but  much  cheaper  to  compute. 


2.7  h man ach -velocity 

float64  h]ii_niach.velocity(mach,  altitude) 
float64  niach; 
float64  altitude: 

‘mach’  Specifies  a  mach  number 
‘altitude’ 

Specifies  an  altitude  (meters) 


hncnach. velocity  computes  the  velocity  (meters/second)  which  corresponds  to  the  passed 
mach  number  for  the  ^ven  altitude. 


2.8  hm .velocity _mach 

float64  h]n_velocity_mach(velocity,  altitude) 
float64  velocity: 
float64  altitude: 
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‘velocity’ 

Specifies  a  velocity  (meters/second) 

‘altitude’ 

Specifies  an  altitude  (meters) 

hin.velocity_mach  computes  the  mach  number  which  corresponds  to  the  passed  velocity  for 
the  given  altitude. 


ADST-TR-W003268 


LibHuUs 


Table  of  Contents 


1  Overview . 1 

2  Examples . 5 

3  Functions . 7 

3.1  hulls_init . 7 

3.2  HULLSJ5ET_EXTERNAL.C0NTR0L . 7 

3.3  hulls^et_direction_si»i:ed . 8 

3.4  HULLS^ET.VELOCITY.GEAR . 9 

3.5  HULLSJSET.VELOCITY_DIRECTION . 10 

3.6  HULLS^ET.VELOCITY.ORIE.NTATION . 11 

3.7  HULLS^ETJ»OSITIO.\J)IRECTION . 11 

3.8  HULLS^ET.GOAL.CORRIDOR . 12 

3.9  HULLSJ5ET.TARGETJD . 13 

3.10  HULLSJSET_TARGETJ*OSITION . 13 

3.11  HULLS-GET-ETA . 14 

3.12  HULLS-GET.TAKEOFF«VLT . 14 

3.13  HULLS^ET-TAKEOFF . 15 

3.14  HULLSJSET_LANDED . 15 

3.15  HULLS^ETJ'LYXEVEL . 15 

3.16  HULLSjGET.TURNJ»ERFORMANCE . 16 

3.17  HULLS.GET-CLIMB_PERFOR.\IANCE . 17 

3.18  HULLS-GETJ’UEL-NEEDED . 18 

3.19  HULLS_GET_MAXJIA.\GE . 18 

3.20  HULLS_GETJ.IMITS . 19 


Chapter  1:  Overview 


1 


1  Overview 


Hulls  is  a  SAF  components  class.  The  purpose  of  a  components  class  is  to  define  a  common 
set  of  functions  which  are  invoked  on  instances  of  that  class,  and  the  semantics  of  those  functions. 
Other  than  defining  these  functional  semantics,  components  classes  don't  actually  do  anything. 

Access  to  hull  functions  is  achieved  through  macros  defined  by  libhulls.  These  macros  invoke 
cnpnt.invoke  with  a  code  number  which  identifies  the  function  to  run.  Libcomponents  then  runs 
this  function  for  the  particular  hull  mode  via  a  jump  table. 

The  table  below  shows  how  the  hulls  component  relationships  have  been  currently  implemented 
via  the  ModSAF  library  structure. 


specific  libraries  generic  library  architectural  library 


libtracked 

libfsa 

libsdssile 

librsa 

libvheeled 


libhulls 

libhulls 

libhulls 

libhulls 

libhulls 


libcomponents 

libcomponents 

libcomponents 

libcomponents 

libcomponents 


As  mentioned  above,  libhulls  requires  the  services  of  libcomponents,  an  architectural  library 
which  provides  a  level  of  abstraction  away  from  the  specific  hulls  component  interfaces.  When  the 
ModSAF  application  gets  set  up  to  run,  the  libhulls  initialization  process  directs  libcomponents 
to  define  a  hull  component  class.  This  information  enables  libcomponents  to  define  a  structure 
to  accommodate  all  of  the  hull  instantiations  a  simulated  object  is  allowed  to  have.  The  libhulls 
initialization  process  also  tells  libcomponents  the  number  of  its  defined  hull  interface  functions. 
This  enables  a  simulated  object’s  user  data  to  be  allocated  enough  space  to  hold  the  address  of 
each  of  the  hull  interface  functions  defined  in  libhulls. 


The  parametric  data  of  libcomponents  identifies  each  component  that  needs  to  be  modeled  when 
a  vehicle  is  simulated.  For  example,  a  component  entry  for  a  T72  tank  might  look  like  this:  (see 
the  file  named  USSR.T72M.paTanis.rdrf 


(SH_Component8  (hull  SN.TrackedHull) 

(turret  SH.GenericTurret) 

(machine-gun  [SN.BallisticGun  I  0]) 
(main-gun  [SH.BallisticGun  I  1]) 
(visual  SN. Visual)) 
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A  T72M  simulated  vehicle  (which  belongs  to  the  safobj  class)  will  have  mni ponent  sub-class  data 
that  tells  the  ModSAF  software  to  maintain  a  structure  that  includes  one  L  ^cracked  instantiation. 


Since  an  application  will  interface  to  libtracked,  libfwa,  librwa,  libwheeled,  or  libmissile  through 
libhuUs,  a  tank’s  movement  control  commands  (which  are  performed  by  libtracked)  and  an  airplane's 
movement  commands  (which  are  performed  by  libfwa)  are  both  issued  via  the  interface  defined  by 
libhuUs.  A  command  to  change  the  controls  is  therefore  the  same  whether  the  hulls  component 
belongs  to  a  tank  or  an  airplane.  What  is  different  are  the  actual  values  used  to  set  the  controls  and 
those  vzdues  are  passed  as  input  to  the  function.  Similarly,  an  appUcation  can  obtain  information 
about  the  state  of  its  huU  though  the  libhuUs  interface.  The  table  below  shows  the  relationship 
between  the  specific  and  generic  library  for  the  huUs  component. 


Instantiations  of 
of  the  library: 

Belong  to  generic 
component  class: 

Have  a  coimand 
interface  defined 

libtracked 

hulls 

libhulls 

libfva 

hulls 

libhulls 

libmissile 

hulls 

libhulls 

librwa 

hulls 

libhulls 

libwheeled 

hulls 

libhulls 

The  interface  to  Ubhulls  is  defined  in  its  public  header  file  (UbhuUs.h).  This  interface  lets  an 
appUcation  set  huU  controls  or  get  huU  information  without  knowing  which  specific  huU  model  is 
being  used.  AppUcations  interface  to  the  tracked,  fwa,  or  missUe  model  primarUy  through  the 
macros  defined  in  Ubhulls.  These  macros  map  to  functions  which  are  invoked  on  instances  of  the 
hulls  sub-class  (such  as  the  Ubtracked  component  instantiated  for  a  tank,  the  Ubfwa  component 
instantiated  for  an  airplane,  or  the  Ubmissile  component  instantiated  for  a  missile). 

The  Ubhulls  interface  is  defined  in  UbhuUs.h,  the  pubUc  header  file  for  Ubhulls.  One  interface 
for  controlUng  vehicle  motion  is  the  HULLS.SET.DIRECTIOH.SPEED  macro  which  maps  to  a  function 
that  sets  a  desired  direction  of  travel  and  a  speed.  Each  macro  is  associated  with  a  function  code 
number  so  that  a  caU  to  the  Ubcomponents  Ubrary  (via  the  cmpntJnvoke  function)  wiU  dispatch 
a  caU  to  the  appropriate  Ubrary  (such  as  Ubfwa,  UbmissUe,  or  Ubtracked).  The  definition  for  this 
macro  might  appear  as  shown  below. 

•define  HULLS.SET.DIRECTIOH.SPEEOCHvid,  Hcnum.  Hdir,  Hsp,  Hntr,  Hma) 
HULLS.IRTEBFACE  .hif; 

.hif.u. set. direct ion_speed. direction  ■  Hdir; 

.hif .u. 8et_direction_speed. speed  >  Hsp; 

_hif .u.set_direction.speed.naz.tum.rate  ■  Hmtr; 

_hif .u.set_direction.speed.]naz_accel  •  Hma; 
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caipnt.invok*(HULLS.SET.DIRECTION_SPEED_FCM,  Hvid,  Hcnua,  (ADDRESS)»,hif ) ; 

} 

The  HULLS.INTERFACE  structure  defined  in  libhulls.h  is  the  structure  that  is  passed  to  any  hull 
function.  This  structure  is  a  union  of  structures  that  each  define  an  argument  list  for  a  hull  function. 
An  abbreviated  example  that  assumes  there  are  only  two  hull  functions  is  shown  below.  Typically 
there  will  be  many  functions  and  therefore  more  strucure  definitions  in  the  union.  The  macros  hide 
this  structure  from  the  users  of  these  functions. 


typedef  struct  hulls.intarface 


> 


union 


•C 


struct  hulls_sat_direction_sp««d 

{ 

float64  *dir«ction; 
f loat64  speed ; 
float64  maz_tum_rate: 
f loat64  max_accel ; 

}  set_direction_speed: 
struct  hulls.set.velocity.gear 

float64  * velocity: 
int32  gear; 
f  loat64  laax.  turn,  rate ; 
f loat64  naz.accel ; 

}  set.velocity.gear; 

>  u; 

HULLS.IirrERFACE; 


Issuing  a  command  to  an  objects’s  hulls  component  is  done  by  invoking  one  of  the  macros 
defined  in  libhulls.  These  macros  identify  the  specific  component  function  which  needs  to  be  called. 
For  example,  invoking  the  HULLS.SET.DIRECTION.SPEED  macro  will  result  in  the  calling  of  the 
setjdirection^peed  specific  component  function.  In  the  public  header  file  of  each  generic  library, 
macros  are  associated  with  a  function  code  number  so  that  a  call  to  the  libcomponents  library  (via 
the  cmpnt invoke  function)  will  dispatch  a  call  to  the  appropriate  function.  The  specific  component 
functions  are  defined  and  installed  by  the  specific  libraries  (libtracked,  libfwa  and  libmissile).  In 
this  case,  all  three  libraries  install  a  function  with  the  same  name,  "setjdirectionjspeed"  (there 
is  no  name  conflict  because  each  function  is  declared  static).  It  is  the  specific  function  (either 
libfwa’s  setjdirection^speed,  libtracked’s  set_directionjspeed,  or  libmissile’s  setjdirection..speed)  that 
is  called  when  the  macro  is  invoked. 


Invoking  the  macro  results  in  two  actions;  (1)  setting  up  of  the  interface  structure  and  (2)  passing 
of  necessary  information  to  libcomponent.  The  macro  passes  the  vehicle  id,  component  number. 
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and  function  pointer  index  to  libcomponent  so  that  the  appropriate  library  (such  as  libtracked, 
libfwa,  or  libmissile)  data  can  be  accessed.  The  requested  function  can  require  input  (s  h  as  a 
direction  and  speed)  and/or  output  (such  as  a  setting)  .  Therefore,  libcomponents  must  also  be 
passed  the  address  of  the  interface  structure  that  holds  this  data. 

In  the  code  segement: 

cnpnt_invoka(HULLS_SET_DIIlECTION.SPE£O.FCM,  Hvid.  Hcnun.  (ADDRESS)t_hif ) ; 

HULLS.SET.DIRECTION.SPEEO.FCN  serves  as  the  function  pointer  index,  Hvid  provides  the  ve¬ 
hicle  id,  Hcnriin  provides  the  component  number,  and  t.hif  provides  the  address  for  the  function’s 
argument  lists. 
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2  Examples 


To  initialize  libtracked,  an  instance  of  the  hull  class: 


tracked_UB«r_data_handle  ■ 

class.reeerve.user.dataCparent.claee,  "tracked" ,  tracked.print) ; 

/*  Tell  libcomponents  tie  are  available.  «/ 

cmpnt.define_inatance(SM,TrackedHull,  1,  *tracked_u*er.data.handle , 

tracked. create,  tracked.destroy, 
HULLS.SET.DIRECTION.SPEED.FCM .  set.dir.speed , 
HULLS_SET.VELOCITY.GEAR.FCir,  set.vel.gear, 
HULLS,SET.VELOCITY.DIRECTIOM.FCH,  set.vel.dir, 
HULLS.SET.VELOCITY_ORIENTATIOir.FCir,  set.vel  ori, 
HULLS.SET.POSITION_DIRECTIOM.FCN,  set.pos  dir, 
HULLS_SET.G0AL.C0RRID0R_FCM ,  eet.goal.corr , 
HULLS.SET.TARGET.ID.FCN,  set.target.id, 
HULLS.SET.TARGET.POSITION.FCN,  set.target.position 
HULLS_GET_ETA.FCN,  get.eta, 

HULLS_GET.TAKEOFF.ALT.FCN,  get.takeofY  alt, 
HULLS.SET.TAKEOFF.FCM,  set.takeoff, 
HULLS.SET,UNDED.FCN,  set.landed, 
HULLS.SET.FLY.LEVEL.FCN , set.f ly.level , 
HULLS.GET.TURN.PERFORMANCE.FCN ,  get. tuncperf orwmce , 
HULLS.GET.CLIMB.PERFORMANCE.FCN ,  get.cliafc.perf oxaance , 
HULLS.GET.FUEL.NEEDED.FCN,  get_fuel.needed, 
HULLS.GET.MAX.RANGE.FCH,  get_aax.raage. 
HULLS.SET,EXTERNAL.C0HTR0L.FCN,  aet.extemal  control 
HULLS.GET.UMITS.FCN,  get.limlts) ; 


To  get  the  component  number  of  my  hull: 


extern  int32  my.hull; 

if  ((my.hull  ■  ca5»nt.locate(vehicle.id,  reader.get.symbolC'hull")))  «■ 
CMPHT.N0T.r0UND) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  hull\n",  vehicle. id) ; 

To  then  give  a  command  to  that  hull  (the  macro  is  defined  by  libhuUs;  it  assembles  a  HULLS. INTERFACE 
structure,  and  calls  copnt. invoke): 


if  (nqr.hull  !■  CMPNT.NOT.FOUHD) 

HULLS.SET.DIRECTION.SPEED(vehicle.id,  hull,  dirvec,  speed,  0.0,  0.0); 
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Chapter  3:  Functions 


3  Functions 


The  following  sections  describe  each  function  provided  by  Ubhulls,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  hullsJnit 

void  hulls.initO : 

hulla.init  initializes  libhuUs.  Call  this  function  after  cmpnt.init,  and  before  any  specific  hull 
init  functions. 


3.2  HULLSJ5ET-EXTERNAL.CONTROL 


HULLS_SET_EXTERNAL.CONTRQL(vehicle_id,  con^nsnt.nunbort  velocity, 

direction,  position,  roll.angle,  »ax.tum.rate8 , 
maz.accel) 

int32  vehicle. id ; 
int32  component. number; 

float64  velocity [3] ; 
float64  direction [3] ; 
float64  posit ion [3] ; 
float64  roll.angle; 
f loat64  maz_tum.rate8  [3] ; 
float64  inaz.accel; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 
‘  component  .number’ 

Specifies  the  hull  component  number 

‘velocity’ 

Specifies  desired  velocity  (meters  per  second) 

‘direction’ 

Specifies  desired  direction 

‘position’ 


Specifies  desired  position 
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‘ma3c_turn>rat®’ 

Specifies  the  maximum  desired  turn  rate  (radians  per  second) 

‘max.accel’ 

Specifies  the  maximum  desired  acceleration  (meters  per  second  squared) 

HULLS.SET.EXTERNAL.CONTROL  is  a  macro  which  sets  a  desired  direction  of  travel  and  movement 
velocity,  as  well  as  an  expected  position.  A  negative  speed  indicates  backward  movement  is  desired. 
It  is  assumed  that  the  hull  should  face  down  the  Y  component  of  the  direction.  Some  hulls  may  not 
support  backward  movement,  in  which  case  they  will  reverse  the  desired  direction.  The  maximum 
turn  rate  (in  radians  per  second)  and  maximum  acceleration  (in  meters  per  second  per  second)  will 
default  to  maximum  if  specified  as  zero. 

The  direction  vector  need  not  be  a  unit  vector  (specific  component  models  may  often  be  able  to 
avoid  normalizing  this  vector  at  all,  saving  a  square  root). 


3.3  HULLSJSET_DIRECTION  JSPEED 

HULLS_SET.DIIlECTION_SPEEO(vehicl«_id,  component. nunbart 

direction,  speed,  fflax.tum.rate.  max.accel) 

int32  vehicle. id; 
int32  component. number; 

float64  direction [3] ; 
float64  speed; 
float64  fflaz.tum.rate; 
float64  maz.accel; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘component.nufflber’ 

Specifies  the  hull  component  number 

‘direction’ 

Specifies  desired  direction 

‘speed’  Specifies  desired  speed  (meters  per  second) 

‘max.tum.rate’ 

Specifies  the  maximum  desired  turn  rate  (radians  per  second) 

‘max.accel’ 

Specifies  the  maximum  desired  acceleration  (meters  per  second  squared) 


HULLS.SET.DIRECTION.SPEEO  is  a  macro  which  sets  a  desired  direction  of  travel  and  a  speed. 
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A  negative  speed  indicates  backward  movement  is  desired.  It  is  assumed  that  the  hull  should  face 
down  the  Y  component  of  the  direction.  Some  hulls  may  not  support  backward  movement,  in  which 
case  they  will  reverse  the  desired  direction.  The  maximum  turn  rate  (in  radians  per  second)  and 
maximum  acceleration  (in  meters  per  second  per  second)  will  default  to  maximum  if  specified  as 
zero. 

The  direction  vector  need  not  be  a  unit  vector  (specific  component  models  may  often  be  able  to 
avoid  normalizing  this  vector  at  all,  saving  a  square  root). 


3.4  HULLS_SET_VELOCITY_GEAR 


HULLS. SET. VELOCITY_GEAR( vehicle. id,  component. number , 

velocity,  gear,  max.tum.rate ,  max.accel) 

int32  vehicle. id; 
int32  component. number; 

float64  velocity [3]; 
int32  gear; 
float64  max.tum_rate ; 
float64  max.accel; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘  component. number’ 

Specifies  the  hull  component  number 

‘velocity’ 

Specifies  the  desired  velocity  (meters  per  second) 

‘gear’  Specifies  the  desired  gear 
‘max.tum.rate’ 

Specifies  the  maximum  desired  turn  rate  (radians  per  second) 

‘max.accel’ 

Specifies  the  maximum  desired  acceleration  (meters  per  second  squared) 


HULLS.SET.VELOCITY.GEAR  is  a  macro  which  sets  a  desired  velocity,  and  a  direction  of  movement 
(forward/backward).  It  is  assumed  that  the  hull  should  face  down  the  Y  component  of  the  direction. 
Some  hulls  may  not  support  backward  movement,  in  which  case  they  will  reverse  the  desired  velocity. 
The  maximum  turn  rate  (in  radians  per  second)  and  maximum  acceleration  (in  meters  per  second 
per  second)  will  default  to  maximum  if  specified  as  zero. 


The  gear  should  be  one  of: 
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HULLS-GEAR.FORWAIID 

Forward  movement 

HULLS_GEAR_REVERSE 

Backward  movement 


3.5  HULLS JSET_VELOCITYJDIRECTION 

HULLS_SET_VELOCITY_DIRECTION(vehicle_id,  component .number, 

velocity,  direction,  roll.angle, 
max_tum.rates ,  maz.accel) 

int32  vehicle. id; 
int32  component.number; 
float64  velocity [3]; 
float64  direction [3] ; 
float64  roll.angle: 
f  loat64  maz.tum.ratea  [3]  ; 
float64  maz.accel: 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘  component.number’ 

Specifies  the  hull  component  number 

‘velocity’ 

Specifies  the  desired  velocity  (meters  per  second) 

‘direction’ 

Specifies  the  desired  direction 
‘roll.angle’ 

Specifies  the  desired  roll  angle  (radians) 

‘maz.tum_rates’ 

Specifies  maximum  desired  turn  rates  (yaw,  pitch,  roll)  in  radians  per  second 

‘max_accel’ 

Specifies  the  maximum  desired  acceleration  (in  meters  per  second  square) 

HULLS.SET.VELOCITY.DIRECTION  is  a  macro  which  sets  a  desired  hull  direction  and  movement 
velocity.  Some  hull  models  require  that  the  direction  and  velocity  vectors  be  colinear;  these  models 
will  strive  to  achieve  the  velocity,  and  will  select  forward  or  backward  movement,  depending  on  the 
dot  product  of  the  two  vectors.  Some  hull  models  also  may  ignore  the  rolLangle.  The  maximum 
turn  rates  are  in  the  order  yaw,  pitch,  roll.  The  maximum  turn  rates  (in  radians  per  second)  and 
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maximum  acceleration  (in  meters  per  second  per  second)  will  default  to  maximum  if  specified  as 
zero  (or  a  NULL  pointer). 


3.6  HULLSJSET .VELOCITY. ORIENTATION 


HULLS.SET.VELOCITY.ORI'^NTATIONCvehicle.id,  component.nunber , 

velocity,  orientation, 
max.tum.rates ,  max.accel) 

int32  vehicle. id; 
int 32  component . numbe  r ; 

float64  velocity [3] ; 
float64  orientation [3] : 
float64  max. turn. rates [3] ; 
float64  max.accel; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘component.nufflber’ 

Specifies  the  hull  component  number 

‘velocity’ 

Specifies  the  desired  velocity 
‘orientation’ 

Specifies  the  desired  orientation  (yaw,  pitch,  roll)  in  radians 
‘max_tum.rate8’ 

Specifies  maximum  desired  turn  rates  (yaw,  pitch,  roll)  in  radians  per  second 

‘max.accel’ 

Specifies  the  maximum  desired  acceleration  (in  meters  per  second  square) 

HULLS.SET.VELOCITY.ORIENTATIOM  is  a  macro  which  .ets  a  desired  hull  orientation  and  move¬ 
ment  velocity.  The  behavior  is  exactly  as  in  HULLS.SET.VELOCITY.DIRECTION,  except  the  direction 
and  roll  angle  are  specified  as  an  angular  triple  (yaw,  pitch,  roll)  in  radians. 


3.7  HULLSJSET  J>OSITIO.\  JDIRECTION 


HULLS.SET.POSITION.DIRECTICNCvehicle.id,  component. number, 

position,  direction) 

int32  vehicle.id; 
int32  component .  r.  be  r ; 
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float64  positionC3] ; 
float64  direction [3] : 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

’  component  .number’ 

Specifies  the  hull  component  number 

‘position’ 

Specifies  the  desired  position 

‘direction’ 

Specifies  the  desired  direction  at  that  position 

HULLS.SET.PQSITIQN.DIRECTIQN  is  a  macro  which  sets  a  desired  hull  position  and  direction. 
The  hull  model  will  achieve  a  position  and  direction  as  close  as  possible  to  these  desires  in  a  manner 
which  is  appropriate  for  the  type  of  hull  being  modeled  (for  a  tracked  hull:  move  to  position,  then 
turn  in  place;  for  a  wheeled  hull:  do  a  three  point  turn;  etc.). 


3.8  HULLS3ET-GOAL-CORRIDOR 


HULLS.SET.GOAL.COIUlIDQR(vahicl«.id,  con^nent. number, 

approach. speed,  position,  direction, 
corridor.vidtb) 

int32  vehicle.id: 
int32  component .number; 

float64  approach.speed; 
float64  positionCS] ; 
floated  direction [3] ; 
floated  corridor. vidth; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘  component  .number’ 

Specifies  the  hull  component  number 
‘approach.8peed’ 

Specifies  the  approach  speed 

‘position’ 

Specifies  the  start  of  the  corridor 

‘direction’ 

Specifies  the  direction  of  the  corridor 
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‘  corridor. width’ 

Specifies  the  width  of  the  corridor 

HULLS.SET.GOAL.CORRIDOR  is  a  macro  which  sets  a  desired  position,  a  desired  speed  to  approach 
that  position  and  a  corridor  (expressed  as  a  direction  and  a  width)  which  is  not  to  be  exceeded  at 
the  time  the  hull  crosses  the  position.  This  is  used,  for  example,  to  approach  a  corner  on  a  road 
without  going  so  fast  you  will  miss  the  corner. 


3.9  HULLSJSET_TARGET JD 


HULLS.SET.TARGET.IDCvehicle.id,  component .number,  id) 
int32  vehicle. id; 
int32  component .number: 
int32  id; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘component.number’ 

Specifies  the  hull  component  number 

‘id’  Specifies  the  ID  of  the  target 

HULLS.SET.TARGET.IO  is  a  macro  which  sets  the  target  which  the  hull  should  pursue  (using 
whatever  method  is  supported  by  that  hull).  Note  that  this  is  primarily  used  by  missile  hulls,  but 
other  hulls  must  support  some  version  of  the  functionality. 


3.10  HULLSJSET.TARGET POSITION 


HULLS.SET.TARGET_POSITION(vehicle_id,  component. number,  position) 
int32  vehicle.id; 
int32  component. number; 

float64  po8ition[3]; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘component_nufflber’ 

Specifies  the  hull  component  number 
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‘position’ 

Specifies  the  target  position 

HULLS.SET.TARGET.POSITION  is  a  macro  which  sets  the  position  which  the  hull  should  pursue 
(using  whatever  method  is  supported  by  that  hull).  Note  that  this  is  primarily  used  by  missile 
hulls,  but  other  hulls  must  support  some  version  of  the  functionality. 


3.11  HULLS_GET»ETA 


HULLS_GET_ETA(vehicle_id,  conponent.number,  position,  eta) 
int32  vehicle. id; 

int32  component .number: 

float64  position [3] ; 

{float64|int32}  *eta; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘  component. number’ 

Specifies  the  hull  component  number 

‘position’ 

Specifies  the  desired  position 

‘eta’  Returns  the  time  it  will  take  to  get  to  that  position 

HULLS.GET.ETA  is  a  macro  which  computes  an  estimated  time  of  arrival  at  a  point  (in  seconds), 
given  current  hull  state,  and  operating  parameters.  Since  this  is  not  a  function,  the  compiler  will 
automatically  cast  the  returned  eta  to  whatever  type  is  needed. 


3.12  HULLS«GET_TAKEOFF_ALT 


HULLS.GET.TAKEOFF.ALTCHvid,  Hcnum,  Haltitude) 
int32  Hvid ; 

int32  Hcnum; 

float64  Haltitude; 


‘Hvid’ 

‘Hcnum’ 


Specifies  the  vehicle  ID 

Specifies  the  hull  component  number 
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^Haltitude’ 

Returns  the  altitude  required  for  completion  of  take  off 

HULLS>GET» TAKEOFF. ALT  returns  (by  reference)  the  altitude  required  for  this  hull  to  complete 
its  take  off. 


3.13  HULLS JSET-TAKEOFF 


HULLS_SET_TAKEOFF(Hvid,  Hcnum,  Haltituda) 
int32  Hvid; 

int32  Hcnum; 

f loat64  Haltitude ; 


‘Hvid’  Specifies  the  vehicle  ID 

‘Hcnum’  Specifies  the  hull  component  number 

‘Haltitude’ 

Specifies  the  target  altitude 


HULLS  .SET.TAKEQFF  sets  the  altitude  for  tlus  huU  to  complete  its  take  off. 


3.14  HULLSJSET-LANDED 


HULLS_SET_LANOED(Hvid.  Hcnum) 
int32  Hvid; 

int32  Hcnum; 


‘Hvid’  Specifies  the  vehicle  ID 

‘Hcnum’  Specifies  the  hull  component  number 


HULLS.SET.LAHOED  places  the  hull  on  the  ground. 


3.15  HULLS J5ET-FLY -LEVEL 


HULLS_SET.FLY_LEVEL(vehicle_id.  component .number,  track,  speed, 

altitude,  fpa,  maz.tum.rate8 ,  maz.accel) 
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int32  vehicle.id; 
int32  component. number; 

float64  track [2] ; 
float64  speed; 
float64  altitude; 
float64  fpa; 

float64  max.tum_rateaC3] ; 
float64  max.accel; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘component.number’ 

Specifies  the  hull  component  number 

‘track’  Specifies  the  2-D  direction  (X-Y  as  a  normalized  vector) 

‘speed’  Specifies  speed  (meters  per  second) 

‘altitude’ 

Specifies  altitude  (meters) 

‘fpa’  Specifies  the  flight  path  angle  (radians) 

‘max.  tum_rat  es  ’ 

Specifies  maximum  desired  turn  rates  (track,  pitch,  roll)  in  radians  per  second 

‘max.accel’ 

Specifies  the  maximum  desired  acceleration  (in  meters  per  second  square) 

HULLS.SET.FLY.LEVEL  is  a  macro  which  sets  a  desired  hull  direction  (track)  speed  and  altitude. 
The  maximum  turn  rates  are  in  the  order  track,  pitch,  roll.  The  maximum  turn  rates  (in  radians 
per  second)  and  maximum  acceleration  (in  meters  per  second  per  second)  will  default  to  maximum 
if  specified  as  zero  (or  a  NULL  pointer). 

Note  that  specifying  a  flight  path  angle  ( fpa)  which  is  too  large,  could  cause  an  airplane  to  stall. 


3.16  HULLS-GET_TURN_PERFORM ANCE 


HULLS .GET.TURK.PERFORMANCE (vahicla.id,  consonant .number , 

max. turn,  easy. turn,  standard. turn,  hzurd.tum) 

int32  vehicle.id; 
int32  component.number; 
float64  max.tum; 
float64  easy. turn; 
float64  standard. turn; 
float64  hard. turn; 
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‘vahicle.id’ 

Specifies  the  vehicle  ID 

‘component.number’ 

Specifies  the  hull  component  number 

‘max. turn’ 

Specifies  the  maximum  turn  rate  for  the  vehicle  in  radians  per  second. 

‘easy.tum’ 

Specifies  the  turn  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an  easy 
turn. 

^standard,  ttim’ 

Specifies  the  turn  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an 
standard  turn. 

‘hard. turn’ 

Specifies  the  turn  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an  hard 
turn. 

HULLS.GET.TURH.PERFORMANCE  is  a  macro  which  queries  the  vehicle  for  current  turn  rates,  which 
can  be  selected  by  a  controller  to  set  the  vehicles  desired  turn  rate. 


3.17  HULLS-GET.CLIMBJPERFORMANCE 


HULLS.GET.CLIHB.PERFORHAHCE ( vehicl •_ id  >  conponent .nunbor , 

iiiaz.climb,  eaBy.cliinb,  standard. cliob,  hard_climb) 

int32  vehlcle.id; 
int32  coBq>onent. number; 

float64  maz_climb; 
float64  easy. climb; 
float64  standard.climb; 
float64  hard.climb; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘component.numbar’ 

Specifies  the  hull  component  number 

‘max.  climb’ 

Specifies  the  maximum  climb  rate  for  the  vehicle  in  radians  per  second. 

‘easy.clinib’ 

Specifies  the  climb  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an  easy 
climb. 
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’standard_cliab’ 

Specifies  the  climb  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an 
standard  climb. 

‘hard.climb’ 

Specifies  the  climb  rate  for  the  vehicle  in  radians  per  second  when  trying  to  do  an  hard 
climb. 

HULLS.GET.CLINB.PERFORMANCE  is  a  macro  which  queries  the  vehicle  for  current  climb  rates, 
which  can  be  selected  by  a  controller  to  set  the  vehicles  desired  climb  rate. 


3.18  HULLS_GET-FUELJNEEDED 


HULLS_GET_FUEL_NEEDED(vehicle_id,  componant.nuaber,  altitude,  speed, 
distance,  fuel.needed) 
int32  vehicle. id; 

int32  cooponent. number; 

float64  altitude: 
floated  speed; 
floated  distance; 
floated  fuel.needed; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘  component.number’ 

Specifies  the  hull  component  number 

‘altitude’ 

Specifies  the  altitude  to  return  to  point. 

‘speed’  Specifies  the  speed  to  return  to  point. 

‘distance’ 

Specifies  the  distance  to  point. 

‘fuel.needed’ 

Specifies  the  fuel  that  is  needed  to  get  to  the  point 


HULLS.GET.FXIEL.NEEDED  is  a  macro  which  determines  how  much  fuel  is  needed  to  get  to  a  point, 
given  the  distance  to  the  point,  and  the  desired  altitude  and  speed  to  use  to  reach  that  point. 


3.19  HULLS_GET.MAX_RANGE 
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HULI.S_GET_MAX_IUNGE(vehicle_id,  cofflponent.niunber ,  majc.range) 
lnt32  vehicle. id; 
int32  component. number: 
float64  maz.range: 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘component.number’ 

Specifies  the  hull  component  number 

‘maz.range’ 

Returns  the  fuel  that  is  needed  to  get  to  the  point 


HULLS.GET.HAX_RANGE  is  a  macro  which  determines  the  maximum  range  of  the  vehicle.  For 
land  vehicles,  it  ignores  factors  such  as  terrain.  For  fixed-wing  aircraft,  it  uses  a  standard  thrust 
rate  and  a  nominal  altitude  of  18000  meters.  In  both  of  the  above  cases,  HULLS.GET.MAX.RAMGE 
bases  its  calculation  on  the  actual  amount  of  fuel  available.  In  the  case  of  a  missile,  this  macro 
returns  the  "maximum  effective  range"  as  specified  in  the  missile’s  parameter  file.  This  is  a  static 
value  and  does  not  change  after  the  missile  is  launched. 


3.20  HULLS.GET J.IMITS 


HULLS.GET.LINITSCvehicle.id,  component_number,  position,  direction, 

maz.speed,  maz.accel,  maz.decel,  maz.tum,  min.radiu8, 
maz.8ideva78 ,  maz_up) 
int32  vehicle.id: 

int32  cofliponent. number; 

Xloat64  position [3] ; 
float64  direction[3] ; 
float64  *max.speed; 
float64  emaz.accel; 
float64  *maz.decel; 
float64  *]Baz.tum; 
float64  *min.radiu8; 
float64  emaz.sideeays ; 
float64  *Biaz.up; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘  component.number’ 

Specifies  the  hull  component  number 
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‘position’ 

Specifies  sample  position  (uses  current  if  NULL  is  passed) 

‘direction’ 

Specifies  sample  directoin  (uses  current  if  NULL  is  passed) 

‘maz.speed’ 

Returns  maximum  possible  speed  in  meters/second 

‘oaz_accel’ 

Returns  maximum  possible  acceleration  in  meters/second /second 

‘inax_decel’ 

Returns  maximum  possible  deceleration  in  meters/second /second 

‘max.  turn’ 

Returns  maximum  possible  turn  rate  in  radians/second 
‘min.radiu8’ 

Returns  minimum  possible  turn  radius  in  meters 
‘inax_8id««ay8’ 

The  maximum  speed  a  vehicle  can  move  sideways.  Zero  for  vehicles  that  can’t  move 
sideways. 

‘max.up’  The  maximum  speed  a  vehicle  can  climb  in  a  hover.  Zero  for  non  hovering  vehicles. 

HULLS.GET.LIMITS  is  a  macro  which  determines  the  maximum  performance  limits  of  a  hull. 
The  position  and  direction  specify  the  state  for  which  limits  are  desired.  If  NULL  is  passed,  the 
current  values  of  the  entity  will  be  used. 


